Blurt MCP Server

What is this?

An MCP server is a small program your AI editor talks to so it can take real actions in the outside world — create files, call APIs, query databases. The blurt-mcp gem is one of those: it lets Claude (or any MCP client) publish to your Blurt queue without leaving the editor.

Under the hood it’s a thin wrapper around the Blurt HTTP API, sharing the same HTTP client as the CLI. Two transports are supported: stdio (local, zero-config) and streamable HTTP (remote, works through a reverse proxy).

Installation

The MCP server lives in the mcp/ directory of the Blurt repository:

git clone https://github.com/fberrez/blurt.sh.git
cd blurt.sh/mcp
bundle install

Claude Code

Claude Code reads MCP config from .mcp.json in the project root. Blurt ships one:

{
  "mcpServers": {
    "blurt": {
      "command": "bundle",
      "args": ["exec", "mcp/bin/blurt-mcp"],
      "env": {
        "BLURT_API_URL": "http://localhost:3000",
        "BLURT_API_KEY": "${BLURT_API_KEY}"
      }
    }
  }
}

Export your API key and start Claude Code from the repo root:

export BLURT_API_KEY=your-secret-key
claude

Claude will launch the MCP server over stdio. Ask it to “create a post saying hello on bluesky and mastodon” — it’ll use the create-post tool.

Cursor & Windsurf

Both read a similar config. The exact file path differs:

Cursor — Settings → MCP → Add new MCP server. Or drop the same JSON in ~/.cursor/mcp.json.
Windsurf — ~/.codeium/windsurf/mcp_config.json

Use the same command / args / env shape as Claude Code.

Tools

Tool	Description
`create-post`	Create and queue a new post for publishing
`list-queue`	List posts in the publishing queue
`list-history`	List already-published posts (system of record)
`get-post`	Fetch a single post by ID or filename
`publish-now`	Force-publish a queued post immediately (bypasses schedule)
`delete-post`	Delete a queued post
`get-platforms`	Show configured publishing platforms

create-post

Inputs: content (markdown), platforms (array), optional title and scheduled_at (ISO 8601).

> use blurt to post "shipping MCP today" to bluesky and mastodon

Post created: 20260415-shipping-mcp-today.md
  Platforms: bluesky, mastodon
  Status:    queue

publish-now

Input: id (post ID or filename). Returns per-platform URLs or failure reasons.

> publish my last queued post now

Published 20260415-shipping-mcp-today.md:

- bluesky: https://bsky.app/profile/did:plc:xxx/post/abc
- mastodon: https://mastodon.social/@you/123456789

Resources

MCP resources are read-only context your editor can pull into a prompt. Blurt exposes two:

URI	Content
`blurt://queue`	JSON snapshot of pending posts (filename, platforms, scheduled_at)
`blurt://platforms`	JSON list of configured platforms and their types

Streamable HTTP transport

For remote MCP — say your Blurt instance runs on a VPS and you’re on a laptop — run the HTTP server instead of stdio:

BLURT_API_URL=http://localhost:3000 \
BLURT_API_KEY=your-key \
bundle exec mcp/bin/blurt-mcp-http

[blurt-mcp-http] Listening on http://0.0.0.0:3333/mcp (puma)

The server mounts the MCP Streamable HTTP endpoint at /mcp. Point your MCP client at it:

{
  "mcpServers": {
    "blurt": {
      "url": "https://blurt.your-vps.com/mcp"
    }
  }
}

You’ll typically want nginx or Caddy in front, with TLS and auth.

How it works

AI editor  ---(MCP)--->  blurt-mcp  ---(HTTP)--->  Blurt API  --->  queue/

The MCP gem has zero filesystem access — every operation is a call against the Blurt HTTP API. Same auth (BLURT_API_KEY), same endpoints as the CLI. Built on the official Ruby MCP SDK.

arrow_back CLI Self-Hosting arrow_forward