Claude Code Plugin

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

Add the marketplace (one time)

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

Install the plugin

claude plugin install ayrshare@ayrshare

Install scopes

Scope	Where it applies
Global (default)	Every project on this machine.
`--scope local`	Current project, not committed to git.
`--scope project`	Current 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

Skill	Purpose
`getting-started`	Orient and connect for first-time use.
`post`	Create, validate, update, and retry posts.
`history`	Retrieve post and platform history.
`analytics`	Pull per-post and account-level analytics.
`comments`	Read, add, and reply to comments.
`messages`	Read and send direct messages and configure auto-responses.
`profiles`	Create and list sub-profiles.
`media`	Validate that media URLs are reachable.
`generate`	AI-draft post copy and recommend hashtags.
`webhooks`	Register, unregister, and list webhooks.
`errors`	Decode Ayrshare error codes.
`draft-in-brand-voice`	Draft post copy in a consistent brand voice.
`plan-and-schedule-campaign`	Plan and schedule a multi-post campaign.

Confirmation hook

A PreToolUse hook asks for confirmation before any action with a live side effect. If you decline, the tool does not run and nothing is sent to Ayrshare. It covers exactly these 12 tools:

create_post
update_post
retry_post
add_comment
reply_comment
send_message
set_auto_response
create_profile: creates a client profile, which uses profile quota.
update_ad: pauses, resumes, deletes, or archives a boosted ad, which changes real ad spend. The same status is also set on the ad’s ad set and campaign, so other ads there change too.
boost_post: boosts a published post as a paid ad, which spends real money from the ad account.
register_webhook and unregister_webhook: change where Ayrshare sends your account’s events, including message and comment content.

The prompt needs plugin version 0.2.2 or later. Earlier versions of the plugin did not show it. To update, run claude plugin marketplace update ayrshare, then claude plugin update ayrshare@ayrshare, and restart Claude Code.

FAQ

Does the plugin validate posts before publishing?

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.

Does it ask before posting to my live accounts?

Yes. A PreToolUse confirmation hook prompts you to approve before any action with a live side effect: create_post, update_post, retry_post, add_comment, reply_comment, send_message, set_auto_response, create_profile, update_ad, boost_post, register_webhook, and unregister_webhook. It needs plugin version 0.2.2 or later.

Can the plugin match my brand's voice?

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.

Can I read analytics to inform the next post?

Yes. The analytics tools return per-post and account-level metrics, so you can read results back and let them guide your next post.

What do I need to use the plugin?

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.

Does posting to X/Twitter need extra setup?

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.

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Install

Install scopes

Credentials

X/Twitter BYO credentials

What it ships

Command

Agents

Skills

Confirmation hook

FAQ

Next steps

Connect & Setup

Tool Catalog

​Install

​Install scopes

​Credentials

​X/Twitter BYO credentials

​What it ships

​Command

​Agents

​Skills

​Confirmation hook

​FAQ

​Next steps

Connect & Setup

Tool Catalog

Install

Install scopes

Credentials

X/Twitter BYO credentials

What it ships

Command

Agents

Skills

Confirmation hook

FAQ

Next steps