Postbase README

@postbasehq/mcp

The Model Context Protocol server for Postbase, the open-source social media scheduler. Add it to Claude, Cursor or any MCP client and let your AI agent draft and schedule posts and threads to X, LinkedIn, Bluesky and Mastodon. (TikTok and YouTube need a video, so schedule those in the app.)

Post everywhere. Even from your AI.

Hosted server (no API key)

Postbase also runs this server for you at https://mcp.postbase.so/mcp, with OAuth sign-in instead of an API key. Add that URL as a custom connector in Claude or ChatGPT, or as a remote MCP server in Cursor, VS Code, Windsurf, Claude Code or Gemini CLI. The MCP config generator prints the exact setup for each one.

Use this npm package when you want an API key instead, or a self-hosted Postbase.

Quick start

Create an API key in your Postbase dashboard under Developers.
Add the server to your MCP client config (see examples below).
Ask your agent: "Schedule this thread for 9am to X and Bluesky."

Example configs

Any MCP client — the minimal config:

config.json

{
  "mcpServers": {
    "postbase": {
      "command": "npx",
      "args": ["@postbasehq/mcp"],
      "env": { "POSTBASE_API_KEY": "pb_live_your_key_here" }
    }
  }
}

Claude Desktop — add the same block to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Then restart Claude Desktop.

Cursor — add it to ~/.cursor/mcp.json (or Settings → MCP):

config.json

{
  "mcpServers": {
    "postbase": {
      "command": "npx",
      "args": ["@postbasehq/mcp"],
      "env": { "POSTBASE_API_KEY": "pb_live_your_key_here" }
    }
  }
}

Local development — point at a Postbase instance running on your machine:

config.json

{
  "mcpServers": {
    "postbase": {
      "command": "npx",
      "args": ["@postbasehq/mcp"],
      "env": {
        "POSTBASE_API_KEY": "pb_live_your_key_here",
        "POSTBASE_API_URL": "http://localhost:3000/api/v1"
      }
    }
  }
}

Tools

Tool	What it does
`list_channels`	List the channels connected to your workspace.
`create_post`	Create a draft, or schedule a post or `thread`: `channel_ids`, `scheduled_at` (ISO 8601 with an offset) or `schedule_in_minutes`, `channel_bodies` for per-channel text, `media_ids` or `media_urls`, `youtube` details, and an `idempotency_key` so retries can't post twice. TikTok posts can only be drafts.
`get_post`	How a post went on each channel: status, live URL, error, retry time and latest metrics.
`update_post`	Edit or reschedule a draft or scheduled post; only the fields you pass change.
`retry_post`	Send a post again to the channels where it failed.
`get_analytics`	Impressions, likes, comments, shares and saves per post and channel, with totals.
`list_media`	List images and videos in your Postbase media library, to attach by id.
`add_media`	Add an image or video to the media library from a public https link.
`list_scheduled`	List scheduled posts, or drafts, published or failed ones with `status`.
`cancel_post`	Cancel a scheduled post by id (it goes back to a draft).
`schedule_thread`	Create a thread (`tweets` in order). Kept for older setups; `create_post` with `thread` does the same.

Environment

Variable	Required	Default
`POSTBASE_API_KEY`	yes	—
`POSTBASE_API_URL`	no	`https://www.postbase.so/api/v1`

For local development against a Postbase instance on your machine, set POSTBASE_API_URL=http://localhost:3000/api/v1.

License

AGPL-3.0-or-later. Part of the open-source Postbase project.