micropub-mcp

MCP server that lets AI agents (Claude Code, Cursor, etc.) create, update, delete, and query posts on any Micropub-compatible blog. Authenticates via IndieAuth with PKCE.

Built with Bun + TypeScript.

Quick Start

1. Install

git clone https://github.com/rmdes/micropub-mcp.git
cd micropub-mcp
bun install

2. Add to Claude Code

Add to your .mcp.json (project or global):

{
  "mcpServers": {
    "micropub": {
      "command": "bun",
      "args": ["run", "/path/to/micropub-mcp/src/index.ts"]
    }
  }
}

3. Authenticate

Tell Claude: "Authenticate with my blog at https://yourblog.com"

This calls micropub_auth, which:

1. Discovers your blog's IndieAuth endpoints

2. Opens your browser to the authorization page

3. You approve access, the callback server catches the token

4. Token is saved to ~/.config/micropub-mcp/<domain>.json

Authentication persists across sessions. You only need to do this once.

4. Start Posting

"Create a note saying Hello from my MCP client!"
"Write an article titled 'My Setup' about my development environment"
"Syndicate a note to Bluesky and Mastodon about the IndieWeb"

Related MCP server: Blogger MCP Server

Tools

micropub_auth

Authenticate with a Micropub-compatible blog via IndieAuth + PKCE.

micropub_create

Create a new post (note, article, photo, bookmark, etc.).

Examples:

Create a note: { content: "Hello world" }
Create an article: { name: "My Title", content: "Article body..." }
Create a bookmark: { like_of: "https://example.com/post" }
Create a reply: { in_reply_to: "https://example.com/post", content: "Great post!" }
Syndicate: { content: "Cross-posted!", syndicate_to: ["https://brid.gy/publish/bluesky"] }
With AI metadata: { content: "AI-assisted post", ai_text_level: "2", ai_tools: "Claude" }

micropub_update

Update an existing post.

Example: { url: "https://blog.com/notes/abc", replace: { content: ["Updated text"] }, add: { category: ["new-tag"] } }

micropub_delete

Delete a post.

micropub_undelete

Restore a previously deleted post.

micropub_query

Query the Micropub server for configuration, posts, or metadata.

Query types:

• config — Server capabilities, syndication targets, post types

• source — Get a post's properties (requires url)

• syndicate-to — Available syndication targets

• post-types — Supported post types

• category — Available categories/tags

• channel — Available channels

micropub_upload

Upload a media file to the server's media endpoint.

Returns the uploaded file's URL, which can be used in photo, video, or audio parameters of micropub_create.

AI Transparency Metadata

Posts can optionally carry metadata disclosing AI involvement. These fields are sent as standard Micropub mf2 properties (ai-text-level, ai-code-level, ai-tools, ai-description).

All fields are optional. If your Micropub server doesn't know about them, it will simply store them as extra properties or ignore them — no special server-side support is required. This works with any standard Micropub endpoint.

If your server does support these fields (e.g., Indiekit with @rmdes/indiekit-endpoint-posts), they can be displayed in the post form UI and used for filtering or labeling posts.

How Authentication Works

┌─────────┐     ┌──────────────┐     ┌─────────────┐     ┌──────────┐
│  Claude  │────>│  MCP Server  │────>│   Browser    │────>│   Blog   │
│  Code    │     │  (this tool) │     │              │     │  Server  │
└─────────┘     └──────────────┘     └─────────────┘     └──────────┘
     │                │                     │                    │
     │  micropub_auth │                     │                    │
     │───────────────>│                     │                    │
     │                │  discover endpoints │                    │
     │                │────────────────────────────────────────>│
     │                │  start callback     │                    │
     │                │  server :19750      │                    │
     │                │  open browser ──────>│                    │
     │                │                     │  authorize ────────>│
     │  "open browser"│                     │                    │
     │<───────────────│                     │<── redirect with   │
     │                │                     │    auth code       │
     │                │<── callback ────────│                    │
     │                │  exchange code ─────────────────────────>│
     │                │<── access token ────────────────────────│
     │                │  save token         │                    │
     │                │  ~/.config/...      │                    │

The callback server runs on localhost:19750 and is a process-level singleton — it persists across MCP tool calls and shuts down after receiving the callback.

Token Storage

Tokens are saved to ~/.config/micropub-mcp/<domain>.json and include:

• Access token

• Refresh token (if provided)

• Expiration time

• Discovered endpoints (micropub, media, token)

Expired tokens are automatically refreshed if a refresh token is available.

Requirements

• Bun 1.0+

• A blog with Micropub + IndieAuth support (e.g., Indiekit, WordPress with IndieWeb plugins, micro.blog)

Indiekit-Specific Notes

If your blog runs Indiekit behind nginx, ensure:

1. CSP form-action: The /auth location must allow form-action * (or at minimum http://localhost:*) so the OAuth consent form can redirect to the local callback server. Without this, clicking "Allow" does nothing (HTTP 499 in logs).

2. Redirect validation: Indiekit's upstream redirect regex (/^\/[\w&/=?]*$/) rejects hyphens in paths like /auth/new-password. If you hit ForbiddenError: Invalid redirect attempted, patch lib/indieauth.js with an expanded regex.

Development

# Run tests
bun test

# Start the MCP server (stdio)
bun run src/index.ts

Architecture

src/
├── index.ts        Entry point — creates MCP server, connects stdio transport
├── tools.ts        7 MCP tool definitions with Zod schemas
├── auth.ts         IndieAuth + PKCE flow, token storage, non-blocking callback server
├── client.ts       Micropub HTTP client (create/update/delete/query/upload)
└── discovery.ts    Endpoint discovery from Link headers + HTML + indieauth-metadata

License

MIT