patreonmcp

MCP server for the official Patreon API v2. Typed tools for campaigns, tiers, members, posts, webhooks, and early-access Lives, plus post creation and editing through Patreon's web editor API.

Python 3.10+.

Features

• Typed MCP tools with structured JSON output.

• Identity, campaigns, tiers, members, and posts through the official API.

• Cursor pagination, explicit field selection, and opt-in PII fields.

• Automatic OAuth refresh with rotated-token persistence.

• Webhook CRUD (creation requires a host allowlist) and early-access Lives.

• Text post creation, editing, publishing, scheduling, and deletion through Patreon's web editor API when a browser session cookie is configured.

• No browser automation. The post client talks directly to Patreon's JSON:API routes.

Related MCP server: X MCP Server

API limits worth knowing

The official Patreon API v2 has no endpoints for creating, editing, or deleting posts:

• Read: identity, campaigns, tiers, members, posts.

• Write: webhooks and early-access Lives.

Patreon's own web app uses separate, undocumented JSON:API routes under /api/posts with a browser session and CSRF ticket. This server speaks to those routes directly for post management. They are not a public API, can change without notice, and currently support text posts only. Post write tools require PATREON_SESSION_COOKIE or PATREON_SESSION_COOKIE_FILE.

Member email, creator notes, and shipping addresses are opt-in tool parameters because they are sensitive; email and address also require extra OAuth scopes. They are also disabled unless the operator sets PATREON_ALLOW_PII=1.

Install

git clone https://github.com/andreanjos/patreonmcp.git
cd patreonmcp
uv sync

Verify the server starts and your credentials work:

PATREON_ACCESS_TOKEN=your_token uv run patreonmcp check

For post write tools, check also verifies the browser session when PATREON_SESSION_COOKIE is set.

Run it directly:

PATREON_ACCESS_TOKEN=your_token uv run patreonmcp serve

Authentication

Creator access token

Get your Creator Access Token from the Patreon Developer Portal. Creator tokens automatically carry all API v2 scopes for the creator's campaign.

export PATREON_ACCESS_TOKEN=...

OAuth refresh (optional)

If your token expires, provide the OAuth client credentials and refresh token so the server can renew it automatically:

export PATREON_CLIENT_ID=...
export PATREON_CLIENT_SECRET=...
export PATREON_REFRESH_TOKEN=...

Set PATREON_TOKEN_FILE to persist rotated tokens across restarts. The file is created with mode 0600; without it, refreshed tokens live only in memory. On POSIX, existing token and cookie files must already be 0600, regular files, owned by the current user, and not symlinks.

export PATREON_TOKEN_FILE="$HOME/.config/patreonmcp/tokens.json"

Web session (post write tools)

The create_post, update_post, publish_post, delete_post, get_managed_post, and list_drafts tools use Patreon's internal web API. They need a logged-in browser session, not an OAuth token.

1. Sign in to https://www.patreon.com in a Chrome-family browser.

2. Open DevTools → Network, reload the page, and select a www.patreon.com request.

3. Copy its full Cookie request header. document.cookie is not enough because the session cookies are HttpOnly.

4. Put the copied header in PATREON_SESSION_COOKIE, or save it to a file and point PATREON_SESSION_COOKIE_FILE at it.

export PATREON_SESSION_COOKIE='session_id=...; a_csrf=...; cf_clearance=...'
# or
chmod 600 ~/.config/patreonmcp/cookies.txt
export PATREON_SESSION_COOKIE_FILE="$HOME/.config/patreonmcp/cookies.txt"

The cookie grants full access to the account. Keep it local, never commit it, and log out of Patreon to invalidate it. The server fetches a CSRF ticket automatically and never prints the cookie.

patreonmcp check verifies both auth modes when both are configured.

Configuration reference

The server reads process environment variables only. .env.example documents the names; it is not loaded automatically. Use your shell, your MCP client's env block, or uv run --env-file .env ....

Setup helper

Generate a client config with absolute paths, then fill in the placeholder token:

uv run patreonmcp init
uv run patreonmcp init --output .mcp.json
uv run patreonmcp init --http --url http://127.0.0.1:8000/mcp

init never prints credentials; it uses explicit REPLACE_... placeholders. Written files are mode 0600.

Inspect the effective configuration with secrets redacted:

uv run patreonmcp config
uv run patreonmcp config --json

MCP client configuration

Use an absolute path to this checkout. Example for Claude Desktop, Claude Code, Cursor, or any client that accepts the standard mcpServers object:

{
  "mcpServers": {
    "patreon": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/patreonmcp",
        "patreonmcp",
        "serve"
      ],
      "env": {
        "PATREON_ACCESS_TOKEN": "your_token_here",
        "PATREON_SESSION_COOKIE": "session_id=...; a_csrf=..."
      }
    }
  }
}

Omit PATREON_SESSION_COOKIE if you only need the read tools. Add PATREON_SESSION_COOKIE_FILE instead when the cookie lives in a local file.

For HTTP transport instead of stdio:

PATREON_ACCESS_TOKEN=... uv run patreonmcp serve --transport streamable-http --host 127.0.0.1 --port 8000

The MCP endpoint is /mcp. Set PATREON_HTTP_BEARER_TOKEN to require a bearer token on every HTTP request; clients then send Authorization: Bearer <token>. Without it, loopback HTTP is unauthenticated. Binding beyond loopback requires both --allow-remote-http and a bearer token; --allow-unauthenticated-http is a second explicit opt-in for reverse-proxy deployments.

{
  "mcpServers": {
    "patreon-http": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "Authorization": "Bearer your-http-token" }
    }
  }
}

CLI post commands

The same post operations are available from the terminal, which is useful for checking a session before wiring up an MCP client:

# Published posts need an OAuth token; drafts need a web session.
uv run patreonmcp post list
uv run patreonmcp post list --drafts --campaign-id 42

uv run patreonmcp post create "Launch notes" --content "Hello patrons" --publish
uv run patreonmcp post create "Draft" --content-file post.html --allow-html
uv run patreonmcp post get POST_ID --content
uv run patreonmcp post update POST_ID --title "New title" --publish
uv run patreonmcp post update POST_ID --clear-tags
uv run patreonmcp post publish POST_ID
uv run patreonmcp post delete POST_ID --yes

uv run patreonmcp post list --json

post create defaults to a draft. --schedule accepts an ISO 8601 time and implies --publish. Deletion requires --yes.

Tools

Pagination

list_members and list_posts return next_cursor. Pass it back as cursor to fetch the next page. page_size accepts 1–1000; when post content is included, the maximum is 100.

Campaign resolution

Tools that need a campaign accept an optional campaign_id. If it is omitted and the token can see exactly one campaign, the server uses it. If several are visible, the tool fails with the visible IDs so the caller can choose.

Post write behavior

create_post defaults to a draft (publish=false). Set publish=true to publish immediately, or publish=true plus scheduled_for to schedule. Use visibility="tiers" with tier_ids for tier-gated posts; public and paid need no tier IDs. Only text_only posts are supported.

Post content and teaser text are escaped as plain text by default. Set allow_html=true to publish raw HTML; that is not sanitized and can include links, embeds, or tracking pixels.

update_post sends a partial update. publish=true publishes; omitting publish saves without changing publication state. delete_post is permanent.

These tools are built on Patreon's browser API (/api/posts/new and PATCH /api/posts/{id}) plus its CSRF ticket endpoint. They are not covered by Patreon's public API contract and can break when Patreon changes its web app.

Webhook triggers

members:create, members:update, members:delete, members:pledge:create, members:pledge:update, members:pledge:delete, posts:publish, posts:update, posts:delete.

Patreon signs webhook deliveries with X-Patreon-Signature, an HMAC-MD5 hex digest of the request body using the webhook secret. Verify it on your receiver.

Webhook creation is disabled unless PATREON_WEBHOOK_ALLOWED_HOSTS names the target host. Webhooks are a persistent data-export channel; approve URI changes and unpausing carefully.

Scopes

Third-party OAuth clients must request these explicitly. During Patreon's OAuth flow, newly requested scopes are added to previously approved scopes.

Security defaults

• Patron email, creator notes, and shipping addresses require PATREON_ALLOW_PII=1.

• Webhook creation is disabled until PATREON_WEBHOOK_ALLOWED_HOSTS is set.

• Webhook signing secrets and Live stream keys are redacted unless explicitly requested.

• Post content and teaser text are escaped unless allow_html=true; post content is capped at 100,000 characters.

• HTTP transport binds to loopback; remote exposure requires --allow-remote-http plus PATREON_HTTP_BEARER_TOKEN (or a second explicit --allow-unauthenticated-http opt-in for a reverse proxy).

• On POSIX, token and cookie files must be regular files owned by the current user with no group/other permissions (chmod 600).

• Base URLs are pinned to www.patreon.com (or loopback for tests), so a rogue environment cannot redirect bearer tokens, refresh tokens, or session cookies to another host.

Development

uv sync --all-groups
uv run pytest
uv run ruff check .
uv run ruff format --check .

Layout:

src/patreonmcp/
  api.py       # endpoint wrappers + JSON:API normalization
  client.py    # auth, token refresh, retries, rate-limit handling
  config.py    # environment, token-file, and session-cookie loading
  models.py    # typed structured-output models
  web_api.py   # undocumented /api post create/edit client + CSRF
  post_cli.py  # post list/get/create/update/publish/delete commands
  http_auth.py # bearer-token guard for streamable HTTP
  server.py    # MCP tool registration
  cli.py       # serve / check / init / config commands

Tests use httpx2.MockTransport; no network or real credentials are required.

Privacy

Patron names, pledge amounts, charge status, and any optional email, note, or address fields are sent to your MCP client and therefore to your model provider. PII fields are disabled unless PATREON_ALLOW_PII=1 is set. Enable optional fields only when the task needs them, and handle the data in accordance with Patreon's Creator Privacy Promise and applicable law.

PATREON_SESSION_COOKIE is a full account credential. Keep it in your local environment or a 0600 file; never commit it, paste it into a chat, or share it with the model provider.

Contributing

Development setup, test commands, and review guidelines are in CONTRIBUTING.md.

Security

Do not report vulnerabilities in public issues. See SECURITY.md. Never commit a Patreon token or session cookie.

License

MIT. See LICENSE.