> ## 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 for Claude Code to publish, schedule, and analyze social posts from your editor — with pre-publish validation, a confirm-before-publish prompt, brand-voice drafting, and analytics read-back.

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

## Install

<Steps>
  <Step title="Add the marketplace (one time)">
    ```bash theme={"system"}
    claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin
    ```
  </Step>

  <Step title="Install the plugin">
    ```bash theme={"system"}
    claude plugin install ayrshare@ayrshare
    ```
  </Step>
</Steps>

### 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`.
</Note>

## Credentials

Provide your Ayrshare API key in either of these ways:

<ul class="custom-bullets">
  <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.
</Warning>

### 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](/apis/overview#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](/additional/mcp-action-connect#xtwitter-byo-credentials).
</Note>

## What it ships

### Command

<ul class="custom-bullets">
  <li>`/ayrshare:setup` — configure or rotate the Ayrshare API key.</li>
</ul>

### Agents

<ul class="custom-bullets">
  <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 publish or send action. It covers exactly these 7 tools:

<ul class="custom-bullets">
  <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>
</ul>

## FAQ

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="Does it ask before posting to my live accounts?">
    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`.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Connect & Setup" icon="plug" href="/additional/mcp-action-connect" horizontal>
    Authentication, profile targeting, and BYO credentials.
  </Card>

  <Card title="Tool Catalog" icon="list" href="/additional/mcp-action-tools" horizontal>
    The 27 tools grouped by domain, with scope and purpose.
  </Card>
</CardGroup>