Chirpie

@chirpie/mcp

The publishing connector for AI agents. Chirpie is one API to post, thread and schedule to X/Twitter, Bluesky, LinkedIn, Threads, Mastodon, Instagram, Facebook and Telegram, covering posting, threads, scheduling, drafts, deletion and analytics. This MCP server puts all of it in front of Claude, Cursor, ChatGPT or any other MCP-capable agent, so "post this to X and LinkedIn, and schedule the follow-up for 9am" is a single sentence rather than a pile of platform SDKs, OAuth dances and rate-limit handling.

Hosted server (recommended)

You don't need to install anything. Point your client at:

https://chirpie.ai/mcp

Sign in when prompted and you're connected. No API key to copy, nothing to keep up to date.

Claude Code

claude mcp add --transport http chirpie https://chirpie.ai/mcp

Claude: add Chirpie from the Claude Connectors Directory, or Customize → Connectors → + → Add custom connector → https://chirpie.ai/mcp (guide)

Cursor: add to .cursor/mcp.json:

{
  "mcpServers": {
    "chirpie": {
      "url": "https://chirpie.ai/mcp"
    }
  }
}

ChatGPT (web, developer mode): Settings → Apps → Create → MCP server URL https://chirpie.ai/mcp → OAuth → Scan Tools (guide)

Prefer a key over OAuth (CI, scripts, clients without an OAuth flow)? Send it as a header:

{
  "mcpServers": {
    "chirpie": {
      "type": "http",
      "url": "https://chirpie.ai/mcp",
      "headers": { "Authorization": "Bearer chirpie_sk_your_key_here" }
    }
  }
}

Local server (this package)

Run the same tool set locally over stdio.

npm install -g chirpie
chirpie login

Claude Code

claude mcp add chirpie -- npx @chirpie/mcp

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "chirpie": {
      "command": "npx",
      "args": ["@chirpie/mcp"]
    }
  }
}

Cursor: add to your MCP settings:

{
  "mcpServers": {
    "chirpie": {
      "command": "npx",
      "args": ["@chirpie/mcp"]
    }
  }
}

The local server resolves credentials in this order:

1. CHIRPIE_API_KEY environment variable
2. ~/.chirpie/config.json (written by chirpie login)

The CLI and this server share that config, so one chirpie login covers both.

Tools

The hosted and local servers expose exactly the same tools. On the hosted server, chirpie_create_key, chirpie_list_keys, chirpie_revoke_key and chirpie_remove_x_keys require API-key auth. Sign in with OAuth and they are not offered, since an OAuth connection must not leave a long-lived key behind or tear down credentials your other connections depend on.

Which tools ask before they run?

Every tool carries a title and the standard MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so your client knows what a call does before it runs it. Listing and reading tools are read-only. Deleting a post or a comment, disconnecting or deactivating an account, editing a queued post, revoking a key and setting or removing your own X app are destructive, and clients such as Claude ask before running them unless you have allowed them. Hiding, unhiding and activating are neither: each has an exact undo. Creating tools are not marked idempotent: the ones that take an idempotency_key only make a retry safe when you pass one. Without a key, repeating chirpie_post, chirpie_thread, chirpie_reply_to_comment or chirpie_retry_first_comment can publish twice, and repeating chirpie_upload_media stores a second copy that expires unused.

Several accounts in one call

chirpie_post and chirpie_thread take account_ids in place of account_id, up to 25 of them. The answer is then a group_id plus one result per account, in the order they were named, and account_configurations gives a single account its own text, media or thread. The accounts that worked stay published when another one's platform refuses, so an agent should read success on each result. Pass the group_id to chirpie_list_posts to read the whole group back.

First comment

chirpie_post and chirpie_thread take first_comment, a comment published under the post the moment it goes out. On a thread it is one comment for the whole thread, published under the last part. X, Threads, Instagram and Facebook only: anywhere else the call is refused with 400 first_comment_unsupported rather than the comment dropped. It counts as one post against the monthly quota.

On a multi-account call the shared first_comment reaches every account unless its account_configurations entry says otherwise: an entry naming a first_comment replaces it for that account, and "first_comment": "" publishes that account with none, which is how one call sends a first comment to the accounts that take one while an account whose platform has none still publishes the post.

Every post carries first_comment back, either null or { text, status, comment_id, error }, with status one of pending, posted and failed. A failed first comment never fails its post, so a published post can be carrying one that did not go out: chirpie_retry_first_comment sends it again, and chirpie_update_post changes the text or, with an empty string, removes it.

Stories, reels and other publishing options

chirpie_post, chirpie_thread and chirpie_update_post take configuration, the per-platform publishing options, keyed by platform. Instagram takes a feed post, a story or a reel, and a Facebook Page takes a feed post or a story. Leave it out and everything publishes to the feed.

{
  "account_id": "...",
  "text": "Three minutes on how we schedule posts.",
  "media_ids": ["..."],
  "configuration": {
    "instagram": {
      "placement": "reel",
      "video_cover_timestamp_ms": 1500,
      "collaborators": ["a_co_author"],
      "share_to_feed": true
    }
  }
}

Each placement carries its own options:

• instagram feed: up to 10 images, collaborators (at most 3 usernames) and user_tags, each of which needs both x and y.
• instagram story: exactly one image or video, no caption (send empty text), no first comment and no collaborators. user_tags may carry coordinates or leave them out.
• instagram reel: exactly one video and no images, plus collaborators, user_tags (the username on its own, since Instagram reads coordinates only on images and stories), cover or video_cover_timestamp_ms but never both, share_to_feed and trial_reel.
• facebook feed: a link, shown as a preview.
• facebook story: exactly one image or video, no text, no first comment and no link.

Nothing is dropped quietly: a block keyed on a platform that takes no options, or a field the chosen placement does not carry, is refused with 400 configuration_unsupported naming the platform and the field. A story and a reel are each a single post, so chirpie_thread refuses either placement. On a multi-account call one block serves every account of that platform, and an account_configurations entry naming its own configuration replaces it for that account. On chirpie_update_post an absent configuration keeps the options the post already has, and "configuration": {} puts it back to a plain feed post.

An Instagram account connects one of two ways, and chirpie_connect_instagram takes via to pick: instagram (the default) signs in with Instagram, and facebook signs in with Facebook and connects the Instagram accounts linked to the Pages the user shares, several at once. Both publish identically, whatever the placement. The one difference is deleting a published post, which works on an account connected via Facebook and is refused with 501 delete_unsupported on one connected through Instagram. Connecting an account that is already connected through the other route moves it rather than adding a second one: it keeps its id and everything it has published, and deleting is the only thing that changes hands. Where the two routes report different Instagram accounts you get a second account instead, so list the accounts again afterwards.

Drafts

draft: true on chirpie_post or chirpie_thread saves the content and sends nothing: no platform call, no quota, and a draft never publishes on its own. A draft is held to far less than a post, so the text may be empty and a draft thread may be a single part, and the answer carries a warnings list saying, per account, what would go wrong if it were sent as it stands.

Promote it with chirpie_update_post: schedule_at queues it, publish: true sends it now, and the two are never valid together. Promotion runs every rule a create runs and takes the quota, so anything refused leaves the draft exactly as it was.

Try it

Once connected, ask your agent:

• "Post to X and LinkedIn: we just shipped v2, but keep the X one shorter."
• "Draft a 5-post thread about why we moved off cron, and schedule it for 9am tomorrow."
• "How did my last Bluesky post do?"
• "Save that as a draft, I will pick the wording tomorrow."
• "Connect my X account."

Kiro power

The root of this repository is also a Kiro power in the Agent Plugins format: plugin.json names it and lists the keywords that activate it, and mcp.json points at the hosted server, https://chirpie.ai/mcp. You sign in to Chirpie in your browser the first time a tool runs, so there is no API key to paste.

Links

• Docs: https://chirpie.ai/docs/mcp?utm_source=npm&utm_medium=readme&utm_campaign=mcp
• API reference: https://chirpie.ai/docs?utm_source=npm&utm_medium=readme&utm_campaign=mcp
• Dashboard: https://chirpie.ai/dashboard?utm_source=npm&utm_medium=readme&utm_campaign=mcp
• Privacy policy: https://chirpie.ai/privacy?utm_source=npm&utm_medium=readme&utm_campaign=mcp
• Terms of service: https://chirpie.ai/terms?utm_source=npm&utm_medium=readme&utm_campaign=mcp
• Support: https://chirpie.ai/support?utm_source=npm&utm_medium=readme&utm_campaign=mcp or [email protected]

MIT © Fireflo LLC

This repository is an automatically maintained source mirror of packages/mcp in the Chirpie monorepo. Pull requests opened here cannot be merged.