buffer-mcp

MCP server for Buffer social media scheduling via the GraphQL API. Works with Claude Desktop, Claude Cowork, and any MCP-compatible AI tool.

The legacy REST API (api.bufferapp.com/1/) is deprecated. This server uses Buffer's current GraphQL API exclusively.

Setup

1. Install dependencies

cd buffer-mcp
bash install.sh

Or manually:

pip install mcp httpx pydantic

2. Get your Buffer credentials

• Access token: Buffer → Settings → API (or Settings → Beta)
• Org ID: Run buffer_get_account after connecting — use the org ID from account.organizations, NOT account.id (they differ and using the wrong one causes silent failures)
• Channel IDs: Run buffer_list_channels to get your Twitter/LinkedIn channel IDs

3. Configure environment variables

Copy .env.example to .env and fill in your values:

cp .env.example .env

4. Add to Claude Desktop / Cowork

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "buffer": {
      "command": "python3",
      "args": ["/absolute/path/to/buffer-mcp/server.py"],
      "env": {
        "BUFFER_ACCESS_TOKEN": "your-token-here",
        "BUFFER_ORG_ID": "your-org-id-here",
        "BUFFER_CHANNEL_TWITTER": "your-twitter-channel-id",
        "BUFFER_CHANNEL_LINKEDIN": "your-linkedin-channel-id"
      }
    }
  }
}

Tools

Tool	Description
buffer_list_channels	List connected social channels with IDs
buffer_get_account	Get account info and find your org ID
buffer_create_post	Schedule a single post (with images, videos, threads, LinkedIn metadata)
buffer_batch_create_posts	Schedule up to 25 posts in one call
buffer_update_post	Edit a scheduled post (atomic delete + recreate)
buffer_delete_post	Remove a post from the queue
buffer_find_post_by_schedule	Look up the canonical ID for a post by its scheduled time
buffer_list_posts	List scheduled posts in your queue
buffer_list_published_posts	List posts that have already been sent
buffer_get_engagement	Pull engagement metrics for a published post (Twitter wired; LinkedIn requires Marketing API)
buffer_get_reply_links	Fetch recent tweet URLs for reply/thread follow-up
buffer_upload_image	Upload a local image or video to Cloudflare R2 and return a Buffer-safe URL
buffer_health_check	Verify token validity and API connectivity

Environment Variables

Variable	Required	Description
BUFFER_ACCESS_TOKEN	Yes	Your Buffer API access token
BUFFER_ORG_ID	Yes	Your Buffer organization ID (from buffer_get_account)
BUFFER_CHANNEL_TWITTER	No	Twitter channel ID — enables "twitter" shorthand
BUFFER_CHANNEL_LINKEDIN	No	LinkedIn channel ID — enables "linkedin" shorthand
BUFFER_TWITTER_USERNAME	No	Your Twitter username for buffer_get_reply_links
TWITTER_BEARER_TOKEN	No	Twitter API v2 bearer token (for reply links + engagement)
CLOUDFLARE_ACCOUNT_ID	No	Cloudflare account ID (for buffer_upload_image)
CLOUDFLARE_R2_API_TOKEN	No	R2 API token with Object:Write permission
CLOUDFLARE_R2_BUCKET_NAME	No	R2 bucket name (default: buffer-media)
CLOUDFLARE_R2_PUBLIC_BASE_URL	No	Public CDN URL for your R2 bucket

Key Notes

Media hosting

Buffer's media fetcher rejects many free CDNs (catbox, imgur return 0-byte or 429 for Buffer's node-fetch UA). Use Cloudflare R2, AWS S3, or another persistent CDN. The buffer_upload_image tool handles R2 uploads automatically when configured.

Twitter threads

To post a thread, use thread_replies in buffer_create_post. Twitter suppresses posts with links in the body — put your CTA URL in the first reply, not the parent tweet.

Post ID rotation (known Buffer bug)

createPost can return a transient ID that differs from the ID returned by buffer_list_posts for the same post. Always use buffer_find_post_by_schedule to get the canonical (deletable) ID before calling buffer_delete_post or buffer_update_post.

Org ID vs Account ID

Buffer exposes both account.id (account-level) and account.organizations[].id (org-level). Using the account ID as the org ID causes silent "Organization not found" errors. Run buffer_get_account and copy the org ID from the organizations list.

License

MIT