pubky-mcp

An MCP server that lets an AI assistant read and publish pubky.app posts, from several Pubky accounts, signed in with Pubky Ring.

• Remote MCP server (Streamable HTTP) with its own OAuth 2.1 authorization server: MCP clients such as Claude Code discover it, register themselves and sign in without any manual setup.

• The only login step is a Pubky Ring QR code. The approving key becomes the operator; its posting session is stored, encrypted, on the server.

• More accounts are linked with link_account: a page, opened through MCP URL elicitation, shows a QR code for the account to add. Each linked account was approved by its own key in Pubky Ring.

• Posts are written to each account's homeserver in the pubky.app format and appear on pubky.app once Nexus has indexed them.

Tools

create_post and repost take the accounts explicitly; there is no default account. A repost is written as pubky.app writes one: {"content": "", "embed": {"kind": "short", "uri": "<original>"}, "kind": "short"}, with the comment in content for a quote; the original is read from its author's homeserver, so a post just published can be reposted at once.

Related MCP server: mastodon-mcp-server

How it works

MCP client ──(Bearer JWT, aud = /mcp)──> /mcp            MCP tools
     │                                     │
     └─ OAuth: /.well-known/*, /reg, /auth, /token        oidc-provider
                         │
                 /interaction/:uid  ── Pubky Ring QR (capabilities /pub/pubky.app/posts/:rw)
                 /connect/:id       ── link another account

• Authorization server: oidc-provider with dynamic client registration, Client ID Metadata Documents, PKCE required, and JWT access tokens bound to the MCP URL (RFC 8707). Refresh tokens for clients registered with the refresh_token grant.

• Sessions: the Pubky Ring flow is the legacy cookie flow, the one Pubky Ring reads today. The session secret is stored AES-256-GCM encrypted with SESSION_ENCRYPTION_KEY, keyed by operator and account.

• Linking: the /connect page must be completed by the operator who asked (MCP spec, URL elicitation, phishing). The browser that signed in is recognised by its session cookie; any other browser must first confirm the operator's key with Pubky Ring (no capabilities requested).

• Storage: one SQLite file (node:sqlite, built into Node) for the OAuth records and the accounts.

Run

Node 24 (TypeScript runs directly, type stripping).

pnpm install
cp .env.example .env    # set SESSION_ENCRYPTION_KEY and PUBLIC_URL
node --env-file=.env src/server.ts

Docker: the image ghcr.io/pastagringo/pubky-mcp is published on every push to main (tags latest and the commit SHA), or docker build -t pubky-mcp .; run it with the same variables and a volume on /data. Put it behind a TLS reverse proxy; PUBLIC_URL is the public HTTPS address.

Add it to Claude Code:

claude mcp add --transport http pubky https://mcp.example.com/mcp

Test

test/e2e.ts plays every part with real protocol messages: the MCP client (discovery, registration, PKCE, refresh), the browser (cookies, redirects) and Pubky Ring (throwaway identities that sign up and approve). It checks the phishing protection, URL elicitation and its completion notice, the stored format of a post (exactly {content, kind}), replies, reposts and quotes, refusals, deletion (48 checks).

Against a local Pubky testnet (synonymsoft/homeserver-testnet, which needs a PostgreSQL on its localhost:5432 with a root role):

PUBKY_TESTNET=localhost node --env-file=.env src/server.ts
E2E_HOMESERVER=8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo E2E_TESTNET=localhost node test/e2e.ts

On the public network, with sign-up codes for the homeserver, E2E_NEXUS=1 also waits for Nexus to index the posts:

E2E_HOMESERVER=<key> E2E_INVITES=<code1>,<code2>,<code3> E2E_NEXUS=1 node test/e2e.ts

test/probe-post.ts checks that a stored session still publishes after a restart. test/probe-foreign.ts checks ALLOWED_HOMESERVERS: a key signed up on another homeserver (FOREIGN_HOMESERVER, FOREIGN_INVITE) approves the sign-in and must be refused (a key hosted nowhere fails earlier and proves nothing).

Known pitfalls

• Avast breaks MCP over HTTP on the machine it protects. Its Web Shield rewrites responses on paths ending in /mcp or /sse, and MCP SSE streams: transfer-encoding: chunked with an unframed body, so Node clients fail with Invalid character in chunk size. Measured on loopback (127.0.0.1, ::1 and the LAN address); reported by others for HTTPS too, and confirmed by Avast staff (fix announced, no version given). On such a machine: add the service's address as an Avast exception, or turn HTTPS scanning off in Web Shield, and run the tests inside Docker. The server stays standard on purpose; a measured server-side workaround (always answer chunked: Avast leaves chunked answers alone) is in commit fbdbd0c, reverted in 5a8a9ff.

• @synonymdev/pubky replaces globalThis.fetch with fetch-cookie (one cookie jar per process) when it is loaded. A test that simulates several browsers in one process must keep the original fetch.

• pubky-app-specs toJson() writes absent fields as null. Both forms exist on pubky.app (posts with and without the null fields, all indexed by Nexus); the service writes the shorter one.

• The capability /pub/pubky.app/posts/:rw is enough to post and delete; pubky.app paths are planned to move (/pub/pubky.app/ → /pub/social/v1/).