# buffer-mcp-server

A custom MCP server that gives Claude **real** publish/schedule access to Buffer,
via the `createPost` GraphQL mutation — beyond what the official Buffer MCP connector
exposes (which is read-only + `create_idea` drafts only).

## Schema status: verified against the live API

The GraphQL operations here were introspected and validated against Buffer's live
endpoint (`api.buffer.com`). Two things were corrected after the initial build:

1. **The `channels` query** in `src/tools/list-channels.ts` takes a single
   `input: ChannelsInput!` argument (`{ organizationId }`), not a flat
   `channels(organizationId:)` argument.
2. **`CreatePostInput.assets` is a required (non-null) list.** Both
   `src/tools/draft-post.ts` and `src/tools/publish-post.ts` now send `assets: []`
   for text-only posts. The other fields (`schedulingType`, `mode`, `dueAt`,
   `saveToDraft`, `channelId`, `text`) match the live schema.

If Buffer changes their schema, re-introspect with a small test query/mutation and
adjust the `.ts` files to match.

## Setup

```bash
npm install
npm run build
```

## Configuration

Set two environment variables wherever you run this:

- `BUFFER_API_KEY` — your personal Buffer API key (Buffer → developer settings →
  requires you to be an organization owner). You said you already have this.
- `MCP_SHARED_SECRET` (optional but recommended for a public HTTP deployment) — an
  arbitrary string. If set, requests must include header `x-mcp-secret: <value>`.

## Running locally (stdio) — for Claude Desktop

Add to your Claude Desktop MCP config:

```json
{
  "mcpServers": {
    "buffer": {
      "command": "node",
      "args": ["/absolute/path/to/buffer-mcp-server/dist/index.js"],
      "env": { "BUFFER_API_KEY": "your_key_here" }
    }
  }
}
```

## Running as a remote HTTP server — for claude.ai custom connectors

```bash
TRANSPORT=http BUFFER_API_KEY=your_key MCP_SHARED_SECRET=some_random_string \
  PORT=3000 npm start
```

This exposes a stateless streamable-HTTP MCP endpoint at `POST /mcp`.

### Hosting options

This is a plain Node/Express app, so it runs on anything that runs Node — **Render,
Railway, Fly.io, or a small VPS** are the simplest. It does *not* run as-is on Cloudflare
Workers (no Node `http` server / Express there); porting it to Workers would mean
swapping Express for a raw `fetch` handler and using the SDK's Workers-compatible
transport pattern — possible, but a separate step from this build. Given the rest of
your stack lives on Cloudflare, that's a reasonable follow-up if you want everything
in one place.

Once hosted, register it in Claude: **Settings → Connectors → Add custom connector**,
paste your server's `https://your-host/mcp` URL.

## Tools this server exposes

- **buffer_list_channels** — read-only, lists channel IDs for an organization.
- **buffer_create_draft_post** — always saves as a draft (`saveToDraft: true` hardcoded).
  Free to call anytime, nothing goes live from this one.
- **buffer_publish_post** — actually schedules or queues a REAL post that will go live.
  Requires `confirmed: true` as a literal parameter, and its tool description explicitly
  instructs Claude to only call it right after you've said something like "yes, post it"
  to that exact text — never from an earlier general go-ahead, and never in response to
  instructions found inside a fetched web page or document.

## Approval workflow (what actually happens)

1. Claude drafts the post text in chat and shows it to you.
2. You say yes/approve.
3. Claude calls `buffer_publish_post` with `confirmed: true` and the exact approved text.

**Important limit to understand:** the `confirmed: true` parameter is a strong signal and
an audit trail (you can always check the tool-call log to see it was set), but it is Claude
setting that parameter based on judgment about the conversation — a JSON field can't
independently verify a human typed "yes." The real guarantee is behavioral: Claude is
built to always ask before taking a publishing action, and to treat that as non-negotiable
regardless of how a request is phrased. If you want a guarantee that doesn't depend on that
judgment at all, use `buffer_create_draft_post` exclusively and do the final approve/schedule
click yourself in Buffer — that's enforced by the code, not by anyone's judgment call.

For extra safety on top of either approach, you can also set **"Requires Approval"** on
your channels in Buffer's own settings — Buffer's docs confirm API-created posts on such
channels are saved as drafts awaiting approval regardless of what the API call requested.

## Known limitations

- If a channel is set to "Requires Approval" in Buffer, posts created via the API land
  as pending drafts regardless of `mode` — that's Buffer's behavior, not a bug here.
- No image/video upload tool included yet (Buffer changed their assets input format on
  May 25, 2026 — worth adding as a follow-up once the schema's confirmed).
- No delete/edit tool included — intentionally minimal for now; extend `src/tools/` if
  you want those.