🔐 Setup

Requirements

• Node.js 20 or later
• A Bluesky account and an App Password

Create an App Password

1. Sign in at bsky.app.
2. Open Settings → App Passwords → Add App Password.
3. Copy the generated password. Use it here, never your main account password.

Environment variables

The server reads two variables. They are the @kud/bsky contract and deliberately not MCP_-prefixed, so the same credentials work with @kud/bsky-cli.

If either is missing the server prints an error to stderr and exits with status 1 before accepting any connection.

Register with a client

Add the server to your MCP client's configuration:

{
  "mcpServers": {
    "bsky": {
      "command": "npx",
      "args": ["@kud/mcp-bsky"],
      "env": {
        "BLUESKY_HANDLE": "alice.example.com",
        "BLUESKY_APP_PASSWORD": "<your-app-password>"
      }
    }
  }
}

Restart the client and the bsky tools appear. The package also installs a mcp-bsky binary, so npx @kud/mcp-bsky runs the server directly over stdio.

Responses and errors

Every tool returns one text block. On success it is the result as indented JSON. On failure it is Error: <message>, so a rejected call (a bad handle, a missing post, an expired session) comes back as readable text rather than a protocol error.

Trying it with the Inspector

From a clone of the repository:

npm install
export BLUESKY_HANDLE=alice.example.com
export BLUESKY_APP_PASSWORD=<your-app-password>
npm run inspect:dev