MCP Server

Chirpie is the publishing connector for AI agents. It speaks MCP (Model Context Protocol), so any MCP-capable agent can post, thread, schedule and read analytics across every account you connect: X, Bluesky, LinkedIn, Mastodon and Telegram, with Threads, Instagram and Facebook coming soon.

Three ways to connect

• Claude, in one click. Chirpie is listed in the Claude Connectors Directory. Add it from the listing and sign in; there is no URL to paste. Claude Code takes the Chirpie plugin or one claude mcp add command.
• Any other AI app, by URL. Add https://chirpie.ai/mcp and sign in. This is how Chirpie works in ChatGPT developer mode, Meta Muse, Cursor and any client that speaks remote MCP.
• On your own machine. The @chirpie/mcp package runs the same server over stdio with your Chirpie login. See Running the server locally.

Step-by-step guides for specific agents: Use Chirpie with Claude (claude.ai, Claude Desktop and Claude Code), Use Chirpie with ChatGPT (ChatGPT developer mode and the OpenAI Responses API) and Use Chirpie with Meta Muse.

How do I connect Chirpie to Claude, Cursor, or ChatGPT?

Add this URL as a remote MCP server in your client and sign in when prompted:

https://chirpie.ai/mcp

That is the whole setup. There is nothing to install and no API key to paste. Your client walks you through Chirpie sign-in the first time and remembers it afterwards. If you would rather run the server on your own machine, the @chirpie/mcp package does the same job over stdio; see Running the server locally below.

Client setup

/plugin marketplace add Firefloco/chirpie-skills
/plugin install chirpie@chirpie-skills

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

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

https://chirpie.ai/mcp

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

https://chirpie.ai/mcp

Can I use an API key instead of signing in?

Yes. If your client doesn't do OAuth, or you're wiring Chirpie into a script or CI job, send an API key as a bearer token instead:

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

Create a key in the dashboard. See Authentication for details.

Read only or full access

When you connect an AI app by signing in, Chirpie asks what the app may do, on a Chirpie screen after you sign in:

• Full access (the default): everything the tools below can do, including publishing, scheduling, editing and deleting posts, answering and moderating comments, uploading media and connecting or disconnecting accounts.
• Read only: the app can list your connected accounts, list and read posts, read analytics and read comments, and nothing else. It is offered only chirpie_list_posts, chirpie_get_post, chirpie_list_accounts, chirpie_analytics, chirpie_list_comments and chirpie_get_x_keys_status, so it never suggests an action it cannot take.

The choice is part of the connection itself and is enforced by Chirpie on every call, not only by what the app is shown. If a read-only connection asks for something it does not cover, the tool answers insufficient_scope and names the permission it needs (for example posts:write).

To change your mind, disconnect Chirpie in your AI app and connect it again, then choose the other option. A connection made before this choice existed keeps full access. API keys are unaffected: give a key scopes to narrow it, and the MCP server likewise offers it only the tools those scopes cover.

How do I connect a social account from chat?

You don't have to leave your agent to connect a platform. Ask it to connect an account and it returns a link for you to open:

"Connect my X account to Chirpie"

The agent calls chirpie_connect_x, hands you an authorization URL, and once you approve it the account shows up in chirpie_list_accounts.

Can I run the server locally?

Yes. The @chirpie/mcp package runs the same server on your own machine over stdio.

1. Authenticate

npm install -g chirpie
chirpie login

The local server reads saved credentials from ~/.chirpie/config.json. No API key in your MCP config.

2. Configure your client

claude mcp add chirpie -- npx @chirpie/mcp

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

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

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

Both servers expose exactly the same tools, so anything below works either way.

What tools does the Chirpie MCP server expose?

chirpie_connect_instagram takes an optional via: "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, which can be several at once. The Facebook route is the one where a published post can be deleted from Chirpie; everything else is identical. An optional reconnect asks Facebook again about anything turned down last time. See Instagram publishing options.

The tools marked "API-key auth only" are registered only when you authenticate the MCP server with an API key. Sign in with OAuth and they are not offered, because an OAuth connection can be disconnected from your client, so it deliberately cannot leave a long-lived key behind or tear down credentials your other connections depend on. Manage API keys in the dashboard, and your own X developer app in account settings. Registering your own X app and checking its status stay available over OAuth.

Which tools ask before they run?

Every tool carries a title and the standard MCP tool annotations, which say what a call does before it runs: readOnlyHint (changes nothing), destructiveHint (can delete, cancel or overwrite something), idempotentHint (a repeat with the same arguments changes nothing further) and openWorldHint (reaches a social platform or another service). Clients use them to decide when to ask you first. Claude, for example, can run a read-only tool without asking and, unless you have allowed it, asks before a destructive one. ChatGPT treats every tool not marked read-only as a write, and may ask you to confirm one depending on the app's permissions and the action.

Editing a queued post, deactivating an account and setting your own X app count as destructive because each replaces or cancels something: an edit overwrites the text, deactivating cancels the account's scheduled posts, and new X keys replace the old ones. Creating tools are never marked idempotent, not even the ones that take an idempotency_key (chirpie_post, chirpie_thread, chirpie_upload_media, chirpie_reply_to_comment and chirpie_retry_first_comment): the key is optional, and without one, repeating a post, thread, reply or first comment can publish it twice.

Tool Details

chirpie_post

chirpie_thread

chirpie_update_post

chirpie_retry_first_comment

A first comment never fails its post, so a published post can be carrying one that did not go out. This re-sends the text the post already holds; to change that text, use chirpie_update_post. A retry that works counts as one post against your monthly quota.

chirpie_list_posts

chirpie_list_accounts

No parameters required. Returns every connected account, including inactive ones. An account with is_active: false and inactive_reason: "plan_limit" is connected but not publishing because your plan's account limit was already full when it was connected. One Facebook authorization can grant several Pages, and Chirpie stores them all rather than dropping any.

chirpie_activate_account

Fails with a plan-limit error when no slot is free. Deactivate another account first.

chirpie_deactivate_account

The account stays connected and can be activated again without reauthorizing.

chirpie_disconnect_account

Ends the connection. The account stops publishing immediately, stops counting against your plan's account limit, and the credential Chirpie stored for it is removed, so connecting it again means authorizing it on the platform again. Every scheduled post queued against it is cancelled and its monthly quota returned; canceled_posts in the response says how many, and they are not restored. Posts the account already published are kept.

Deactivate instead when the account should come back later without reauthorizing.

chirpie_analytics

The numbers come from a snapshot at most an hour old, so calling this often costs nothing. Reserve refresh for the moment somebody is actually looking. See Analytics.

chirpie_list_comments

Returns the comments plus capabilities for that platform and a sync object saying how fresh they are. Replying to one publishes a post, so it uses one post from the monthly quota; listing and hiding do not.

chirpie_reply_to_comment

chirpie_hide_comment

Facebook, Instagram and Threads support hiding, and all three are coming soon. Elsewhere the tool reports that the platform has no hide rather than reporting success.

chirpie_delete_comment

Most platforms allow deleting only replies you wrote. Check capabilities.delete_any from chirpie_list_comments before deleting someone else's comment. On Facebook, Instagram, Threads and LinkedIn the replies under a deleted comment are deleted with it.

chirpie_set_x_keys

Registers your own X developer app so X accounts connect through it and post against your X API credits. See Bring your own X keys.

chirpie_get_x_keys_status

No parameters required. Returns configuration status and the callback URI to register on your X app, never the client secret.

chirpie_remove_x_keys

No parameters required. Removes your own X developer app. API-key auth only. Over OAuth, remove the app from account settings instead.

What can I ask my agent to do?

Once configured, you can ask Claude:

• "Post a tweet saying 'Just shipped a new feature!'"
• "Post to Bluesky saying 'Hello from Chirpie!'"
• "Post to LinkedIn about our new product launch"
• "Post to Mastodon saying 'Hello from Chirpie!'"
• "Send a message to our Telegram channel"
• "Post this image to X and Mastodon with alt text"
• "Schedule a LinkedIn post for Tuesday at 9am in my timezone"
• "Post this to X, Bluesky and LinkedIn at once, with a shorter version for Bluesky"
• "Create a thread about the benefits of TypeScript"
• "Show me my recent posts"
• "What are the analytics for my last post?"
• "Schedule a post for tomorrow at 9am saying 'Good morning!'"
• "Save this as a draft, I will decide on the wording later"
• "Show me my drafts, then publish the one about the launch"
• "List my connected accounts"
• "Connect my X account"

How does authentication work?

Hosted server, either works:

1. Sign in through your client's connector flow (OAuth). Recommended: there is no key to store or leak, access lasts only as long as your client keeps its token, and you choose Full access or Read only when you connect.
2. Send Authorization: Bearer chirpie_sk_… if your client supports custom headers. API keys can be revoked at any time from the dashboard.

Any app can register itself to sign in, as the MCP specification requires, and every sign-in uses PKCE. Registration accepts only https redirect addresses, plain http on localhost, 127.0.0.1 or [::1], or the editor schemes of Cursor, VS Code and Windsurf, and the app must give a name. Before you approve, the Chirpie screen shows where you will be sent back to, such as claude.ai or the Cursor app, and says so when Chirpie does not recognise that app. The name an app gives itself is its own choice, so check the destination too.

Local server, resolves your API key in this order:

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

Both the CLI and the local MCP server share the same config file. One chirpie login authenticates both.

Rate limits and plan quotas are identical across the API, SDK, CLI and both MCP servers. See Rate Limits.

Frequently asked questions

Do I need to install anything to use Chirpie's MCP server?

No. https://chirpie.ai/mcp is a hosted, remote MCP endpoint. Paste it into your client, sign in, and the tools appear. The @chirpie/mcp npm package is only needed if you specifically want to run the server locally.

Which AI clients work with it?

Any client that speaks MCP over Streamable HTTP. Claude (web, desktop and Claude Code), Cursor, and ChatGPT are the ones with setup steps above, with full guides in Use Chirpie with Claude and Use Chirpie with ChatGPT, and Meta Muse has its own guide: Use Chirpie with Meta Muse. Clients that only speak stdio can use the local @chirpie/mcp package instead.

Do I need developer accounts on X, LinkedIn, or Mastodon?

No. Chirpie holds the platform integrations. You connect your social accounts once, from the dashboard or by asking your agent, and Chirpie handles OAuth, token refresh and publishing.

Is the hosted server free to use?

Yes, on every plan including the free one. The MCP server is an interface onto the same API, so it consumes the same monthly post quota. See Rate Limits.

Can my agent schedule posts through MCP?

Yes. Pass schedule_at to chirpie_post or chirpie_thread, either as an absolute ISO 8601 instant (2026-04-01T14:00:00Z) or as a local time with no offset (2026-11-01T09:30:00) alongside timezone: "America/New_York". Daylight saving is worked out for the date named, which is the thing an offset computed today gets wrong. See Scheduling and Timezones.

How do I stop my agent posting twice when a call times out?

Pass idempotency_key on chirpie_post, chirpie_thread, chirpie_upload_media, chirpie_retry_first_comment or chirpie_reply_to_comment. The same key with the same request replays the first answer for 24 hours instead of publishing again. A retry that arrives while the first call is still running answers 409 idempotency_in_progress: retry once more to collect the replay. See Idempotency.

Can I give my agent a key that can only post?

Yes. Create a key with scopes, either in the dashboard or with chirpie_create_key's scopes parameter, and the agent's calls outside those scopes are refused with 403 insufficient_scope. See Scopes.

Can I connect an AI app that can only read?

Yes. Choose Read only on the Chirpie screen that appears when you sign in. The app can then list your accounts, read posts, analytics and comments, and is not offered any tool that publishes, edits, deletes or connects anything. See Read only or full access.

Can my agent save a draft instead of posting?

Yes. Pass draft: true to chirpie_post or chirpie_thread and the post is saved without being sent: nothing reaches the platform and nothing counts against your quota. The answer lists anything that would go wrong if it were sent as it stands. Finish it with chirpie_update_post, then promote it with schedule_at to queue it or publish: true to send it now. See Drafts.

What happens if a tool call fails?

Tools return the API's error code and message verbatim, so your agent can act on it, for example rate_limited or a plan-quota error. The full list is in Error Codes.