> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Plugin

> Install the Ayrshare plugin in Claude Code, set your API key and X/Twitter BYO credentials, and review its agents, skills, and confirmation hook.

The Ayrshare plugin for Claude Code bundles the [MCP Server](https://www.ayrshare.com/docs/additional/mcp-action-server.md) 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](https://github.com/ayrshare/ayrshare-social-media-api-claude-plugin).

## Install

**1. Add the marketplace (one time)**

```bash theme={"system"}
claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin
```

**2. Install the plugin**

```bash theme={"system"}
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. |

> [!NOTE]
>
> Claude Code's CLI calls the global scope `--scope user`.

## Credentials

Provide your Ayrshare API key in either of these ways:

<ul>
  <li>Run `/ayrshare:setup` to configure or rotate the key.</li>
  <li>Set the `AYRSHARE_API_KEY` environment variable.</li>
</ul>

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.

> [!WARNING]
>
> 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](https://www.ayrshare.com/docs/apis/overview.md#xtwitter-byo-credentials)). The bundled `.mcp.json` already declares both X BYOK headers with empty defaults, alongside `Authorization` and `Profile-Key`:

```json theme={"system"}
"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).

> [!NOTE]
>
> 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](https://www.ayrshare.com/docs/additional/mcp-action-connect.md#xtwitter-byo-credentials).

## What it ships

### Command

<ul>
  <li>`/ayrshare:setup` — configure or rotate the Ayrshare API key.</li>
</ul>

### Agents

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

### 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:

<ul>
  <li>`create_post`</li>
  <li>`update_post`</li>
  <li>`retry_post`</li>
  <li>`add_comment`</li>
  <li>`reply_comment`</li>
  <li>`send_message`</li>
  <li>`set_auto_response`</li>
  <li>`create_profile`: creates a client profile, which uses profile quota.</li>
  <li>`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.</li>
  <li>`boost_post`: boosts a published post as a paid ad, which spends real money from the ad account.</li>
  <li>`register_webhook` and `unregister_webhook`: change where Ayrshare sends your account's events, including message and comment content.</li>
</ul>

> [!NOTE]
>
> 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

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](#xtwitter-byo-credentials) above.

## Next steps

> [card] [Connect & Setup](https://www.ayrshare.com/docs/additional/mcp-action-connect.md)
>
> Authentication, profile targeting, and BYO credentials.

> [card] [Tool Catalog](https://www.ayrshare.com/docs/additional/mcp-action-tools.md)
>
> The 33 tools grouped by domain, with scope and purpose.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.