Skip to main content
The Ayrshare plugin for Claude Code bundles the MCP Server configuration, a setup command, agents, skills, and a safety hook. With it installed, you can publish posts, fetch history and analytics, manage profiles, and more — directly from Claude Code. Before anything goes live, the agent validates each post against the target network’s rules and asks you to confirm, catching avoidable rejections up front. Post history is available for matching a brand’s voice, and analytics can be read back to inform the next post. The plugin is open source. See the repository for internals: ayrshare/ayrshare-social-media-api-claude-plugin.

​
Install

1

Add the marketplace (one time)

claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin
2

Install the plugin

claude plugin install ayrshare@ayrshare

​
Install scopes

ScopeWhere it applies
Global (default)Every project on this machine.
--scope localCurrent project, not committed to git.
--scope projectCurrent project, committed and shared with your team.
Claude Code’s CLI calls the global scope --scope user.

​
Credentials

Provide your Ayrshare API key in either of these ways:
  • Run /ayrshare:setup to configure or rotate the key.
  • Set the AYRSHARE_API_KEY environment variable.
The plugin’s bundled .mcp.json already declares the Authorization header plus the optional Profile-Key and X BYOK headers, each with an empty default (${VAR:-}), so you enable a header simply by setting its environment variable (Claude Code substitutes the values at startup). To target a sub-profile on every call, set AYRSHARE_PROFILE_KEY (via /ayrshare:setup or your settings.json env block) and restart Claude Code; the bundled Profile-Key header carries it, and stays empty (treated as not provided) when unset. To target a sub-profile for a single call instead, pass a profileKey tool argument (no config change needed). You do not need to edit the bundled .mcp.json, and you should not, because claude plugin update overwrites it.
The MCP server initializes at session start. Restart Claude Code after installing the plugin or changing your key.

​
X/Twitter BYO credentials

Posting to X/Twitter requires your own X Developer App credentials (the X BYO-key mandate, effective March 31, 2026; see the API Overview). The bundled .mcp.json already declares both X BYOK headers with empty defaults, alongside Authorization and Profile-Key: 
"headers": {
  "Authorization": "Bearer ${AYRSHARE_API_KEY}",
  "Profile-Key": "${AYRSHARE_PROFILE_KEY:-}",
  "X-Twitter-OAuth1-Api-Key": "${X_TWITTER_OAUTH1_API_KEY:-}",
  "X-Twitter-OAuth1-Api-Secret": "${X_TWITTER_OAUTH1_API_SECRET:-}"
}
So you only set the matching environment variables (X_TWITTER_OAUTH1_API_KEY, X_TWITTER_OAUTH1_API_SECRET) via /ayrshare:setup or your settings.json env, then restart Claude Code; you do not edit the bundled .mcp.json (it is overwritten on claude plugin update). Set both or neither: with neither set an X/Twitter call returns error 419 (x_credentials_required); with only one set it returns error 400. This is one key pair per Ayrshare account, sent on every X-targeting request (the same pair for all sub-profiles).
Prefer a raw connection over the plugin? The same BYO headers can be passed via claude mcp add --header — see Connect & Setup → X/Twitter BYO credentials.

​
What it ships

​
Command

  • /ayrshare:setup — configure or rotate the Ayrshare API key.

​
Agents

  • social-manager: publishes, schedules, and analyzes content across platforms.
  • profile-manager: creates and lists profiles and mints JWT social-linking URLs for client profiles under a Business account.
  • insights-analyst: read-only reporting. Pulls metrics and post history and summarizes performance; never publishes, comments, messages, or modifies anything.

​
Skills

SkillPurpose
getting-startedOrient and connect for first-time use.
postCreate, validate, update, and retry posts.
historyRetrieve post and platform history.
analyticsPull per-post and account-level analytics.
commentsRead, add, and reply to comments.
messagesRead and send direct messages and configure auto-responses.
profilesCreate and list sub-profiles.
mediaValidate that media URLs are reachable.
generateAI-draft post copy and recommend hashtags.
webhooksRegister, unregister, and list webhooks.
errorsDecode Ayrshare error codes.
draft-in-brand-voiceDraft post copy in a consistent brand voice.
plan-and-schedule-campaignPlan and schedule a multi-post campaign.

​
Confirmation hook

A PreToolUse hook asks for confirmation before any publish or send action. It covers exactly these 7 tools:
  • create_post
  • update_post
  • retry_post
  • add_comment
  • reply_comment
  • send_message
  • set_auto_response

​
FAQ

Yes. The plugin runs validate_post to dry-run your content against each network’s rules — length, format, and media requirements — before it publishes, so you catch avoidable rejections up front.
Yes. A PreToolUse confirmation hook prompts you to approve before any publish or send action: create_post, update_post, retry_post, add_comment, reply_comment, send_message, and set_auto_response.
Yes. The draft-in-brand-voice skill reads your post history to draft new copy in a consistent brand voice. It produces drafts only — nothing publishes without your confirmation.
Yes. The analytics tools return per-post and account-level metrics, so you can read results back and let them guide your next post.
An Ayrshare API key (a Business plan key for profiles and sub-profiles) and Claude Code. Configure the key with /ayrshare:setup or the AYRSHARE_API_KEY environment variable, then restart Claude Code.
Yes. X/Twitter requires your own OAuth 1.0a credentials, added as two connection headers (X-Twitter-OAuth1-Api-Key and X-Twitter-OAuth1-Api-Secret). See X/Twitter BYO credentials above.

​
Next steps

Connect & Setup

Authentication, profile targeting, and BYO credentials.

Tool Catalog

The 27 tools grouped by domain, with scope and purpose.