Connect your AI agent to Postbean with MCP

Postbean speaks MCP (Model Context Protocol), the standard AI assistants use to work with outside tools. Connect it once and your assistant can draft, schedule and publish posts in your workspace — in plain language, without you opening the app.

“Write a post about the new pricing, attach this video, and schedule it for Tuesday at 9” becomes something your assistant just does.

It works with Claude Desktop, Claude Code, Cursor, and any other client that supports MCP.

What your assistant can do

Everything the composer can, over the same permissions your account already has:

• List your connected accounts and see what is scheduled
• Upload an image or a video and attach it to a post
• Write a caption once, then adjust it per network — including the first comment
• Set the per-network options that each platform requires (TikTok audience, YouTube Short vs video, Instagram Reel vs feed…)
• Schedule, reschedule, cancel, publish
• Generate captions and full campaigns with AI (this spends credits)

It never publishes on its own. Publishing happens only when you ask for it in those words. Everything else ends as a draft or a scheduled post that you can review in the app first.

Before you start

The developer API is a paid add-on. Turn it on and create a key from Settings → Developers; that page shows the price.

When you create the key you pick which permissions it carries, and they cannot be added later. Give it the narrowest set that does the job — a key that writes drafts but cannot publish or delete is a real safety net:

Permission	What it allows
accounts:read	View connected accounts
posts:read	Read posts and renders
drafts:write	Create and edit drafts
posts:publish	Publish to networks
posts:delete	Delete posts
credits:read	View credits
ai:generate	Generate content with AI
campaigns:generate	Generate campaigns

The token is shown once. Copy it somewhere safe before closing the page.

Connect it

There are two ways in, and they do the same things. The difference is where the server runs, which matters only when you upload files your assistant has on your own computer.

	Runs on	Uploading a local file
Hosted	Postbean’s servers	Needs a public URL for the file
Local	Your machine, through npx	Reads the file straight off your disk

Pick hosted unless your assistant works with files it has locally.

Hosted

Nothing to install. Point your client at the endpoint with your key as a bearer token.

Claude Code

claude mcp add --transport http postbean https://postbean.app/mcp/postbean --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop, Cursor, or any client with an MCP JSON config

{
  "mcpServers": {
    "postbean": {
      "type": "http",
      "url": "https://postbean.app/mcp/postbean",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Local

Runs on your machine from npm. Needs Node 18 or newer; npx downloads it the first time.

Claude Code

claude mcp add postbean --env POSTBEAN_API_TOKEN=YOUR_TOKEN -- npx -y @postbean/mcp

Claude Desktop, Cursor, or any client with an MCP JSON config

{
  "mcpServers": {
    "postbean": {
      "command": "npx",
      "args": ["-y", "@postbean/mcp"],
      "env": { "POSTBEAN_API_TOKEN": "YOUR_TOKEN" }
    }
  }
}

Check it worked

Ask your assistant to list your connected accounts. If it names them, you are connected. If the tools do not appear at all, restart the client — most clients read their tool list once at startup.

Publishing, end to end

A normal run looks like this, and you can stop at any step:

1. “Which accounts do I have connected?” — confirms the connection and gives your assistant the account ids it needs.
2. “Draft a post about X for Instagram and LinkedIn.” — it writes the caption and creates a draft. Nothing has left your workspace.
3. “Attach this video.” — see Adding media below.
4. “Show me the post.” — it reads the draft back, including the per-network captions and the link to open it in the composer.
5. “Change the LinkedIn caption to…” — edits happen on the same post. If your assistant creates a second draft instead of editing the first, tell it to edit; that is the mistake this API sees most.
6. “Schedule it for Tuesday at 9.” or “Publish it now.”

Some networks have required options and Postbean will refuse the post without them, with a message saying what is missing. TikTok is the strictest: it needs an audience, and your assistant has to read the real options off your account rather than guess one.

Adding media

Three ways to hand over a file, and your assistant picks based on what it has:

• A public URL — works on both servers. The download runs in the background, so the upload returns immediately and the file lands a few seconds later. If you publish in the meantime the post simply waits for it.
• A local path — only on the local (stdio) server, since only that one can see your disk.
• Small images inline — under 8 MB, for a logo or a screenshot.

Limits are the same everywhere: 100 MB per video, 8 MB per image.

If you are on the hosted server with a file that has no public URL, your assistant does not need to host it anywhere — the API takes the bytes directly.

When something is refused

If a tool says the key lacks a permission, or that you may not touch that post, that is the answer, not an obstacle. Permissions are fixed when a key is created, so it needs a new key, not a retry — and only you can issue one. The same applies to the REST endpoints behind the tools: same key, same rules.