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

# Plugin do Claude Code

> Instale o plugin da Ayrshare para o Claude Code para publicar, agendar e analisar publicações sociais direto do seu editor — com validação pré-publicação, prompt de confirmação antes de publicar, redação com voz da marca e leitura de análises.

O plugin da Ayrshare para Claude Code inclui a configuração do [MCP Server](/additional/mcp-action-server), um comando de setup, agents, skills e um hook de segurança. Com ele instalado, você pode publicar, obter histórico e análises, gerenciar profiles e muito mais — diretamente do Claude Code. Antes de qualquer coisa ir ao ar, o agente valida cada publicação contra as regras da rede de destino e pede sua confirmação, evitando rejeições evitáveis logo de cara. O histórico de publicações fica disponível para combinar com a voz da marca, e as análises podem ser lidas para orientar a próxima publicação.

O plugin é open source. Veja o repositório para detalhes internos: [ayrshare/ayrshare-social-media-api-claude-plugin](https://github.com/ayrshare/ayrshare-social-media-api-claude-plugin).

## Instalar

<Steps>
  <Step title="Adicione o marketplace (uma vez)">
    ```bash theme={"system"}
    claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin
    ```
  </Step>

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

### Escopos de instalação

| Escopo            | Onde se aplica                                           |
| ----------------- | -------------------------------------------------------- |
| Global (padrão)   | Todo projeto nesta máquina.                              |
| `--scope local`   | Projeto atual, não commitado no git.                     |
| `--scope project` | Projeto atual, commitado e compartilhado com sua equipe. |

<Note>
  A CLI do Claude Code chama o escopo global de `--scope user`.
</Note>

## Credenciais

Forneça sua API Key da Ayrshare de uma destas formas:

<ul class="custom-bullets">
  <li>Execute `/ayrshare:setup` para configurar ou rotacionar a chave.</li>
  <li>Defina a variável de ambiente `AYRSHARE_API_KEY`.</li>
</ul>

O `.mcp.json` incluído no plugin já declara o header `Authorization`, além dos headers opcionais `Profile-Key` e BYOK do X, cada um com um valor padrão vazio (`${VAR:-}`), para que você ative um header apenas definindo sua variável de ambiente (o Claude Code substitui os valores ao iniciar). Para direcionar a um sub-profile em cada chamada, defina `AYRSHARE_PROFILE_KEY` (via `/ayrshare:setup` ou pelo bloco `env` do seu `settings.json`) e reinicie o Claude Code; o header `Profile-Key` incluído o transporta e permanece vazio (tratado como não fornecido) quando não definido. Para direcionar a um sub-profile em uma única chamada, passe um argumento `profileKey` na tool (nenhuma mudança de configuração é necessária). Você não precisa editar o `.mcp.json` incluído, e não deve fazê-lo, porque `claude plugin update` o sobrescreve.

<Warning>
  O MCP Server é inicializado no início da sessão. **Reinicie o Claude Code** após instalar o plugin ou alterar sua chave.
</Warning>

### Credenciais BYO do X/Twitter

Publicar no X/Twitter exige suas próprias credenciais de X Developer App (o mandato de chaves BYO do X, em vigor desde 31 de março de 2026; veja a [Visão Geral da API](/apis/overview#xtwitter-byo-credentials)). O `.mcp.json` incluído já declara ambos os headers BYOK do X com valores padrão vazios, junto de `Authorization` e `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:-}"
}
```

Basta então definir as variáveis de ambiente correspondentes (`X_TWITTER_OAUTH1_API_KEY`, `X_TWITTER_OAUTH1_API_SECRET`) via `/ayrshare:setup` ou no `env` do seu `settings.json` e **reiniciar o Claude Code**; você não edita o `.mcp.json` incluído (ele é sobrescrito em `claude plugin update`). Defina **ambas** ou nenhuma: sem nenhuma definida, uma chamada ao X/Twitter retorna erro `419` (`x_credentials_required`); com apenas uma definida, retorna erro `400`. Este é um par de chaves por conta Ayrshare, enviado em cada requisição direcionada ao X (o mesmo par para todos os sub-profiles).

<Note>
  Prefere uma conexão bruta ao plugin? Os mesmos headers BYO podem ser passados via `claude mcp add --header` — veja [Conectar e Configurar → Credenciais BYO do X/Twitter](/additional/mcp-action-connect#xtwitter-byo-credentials).
</Note>

## O que o plugin inclui

### Comando

<ul class="custom-bullets">
  <li>`/ayrshare:setup` — configura ou rotaciona a API Key da Ayrshare.</li>
</ul>

### Agents

<ul class="custom-bullets">
  <li>`social-manager`: publica, agenda e analisa conteúdo em várias plataformas.</li>
  <li>`profile-manager`: cria e lista profiles e gera URLs de vinculação social JWT para profiles de clientes sob uma conta Business.</li>
  <li>`insights-analyst`: relatórios somente leitura. Puxa métricas e histórico de publicações e resume o desempenho; nunca publica, comenta, envia mensagens ou modifica algo.</li>
</ul>

### Skills

| Skill                        | Propósito                                                          |
| ---------------------------- | ------------------------------------------------------------------ |
| `getting-started`            | Orientar e conectar para o primeiro uso.                           |
| `post`                       | Criar, validar, atualizar e reenviar publicações.                  |
| `history`                    | Obter histórico de publicações e de plataforma.                    |
| `analytics`                  | Puxar análises por publicação e no nível da conta.                 |
| `comments`                   | Ler, adicionar e responder a comentários.                          |
| `messages`                   | Ler e enviar mensagens diretas e configurar respostas automáticas. |
| `profiles`                   | Criar e listar sub-profiles.                                       |
| `media`                      | Validar se URLs de mídia são acessíveis.                           |
| `generate`                   | Redigir texto de publicação com IA e recomendar hashtags.          |
| `webhooks`                   | Registrar, cancelar registro e listar webhooks.                    |
| `errors`                     | Decodificar códigos de erro da Ayrshare.                           |
| `draft-in-brand-voice`       | Redigir texto de publicação em uma voz de marca consistente.       |
| `plan-and-schedule-campaign` | Planejar e agendar uma campanha com várias publicações.            |

### Hook de confirmação

Um hook `PreToolUse` pede confirmação antes de qualquer ação de publicar ou enviar. Ele cobre exatamente estas 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="O plugin valida publicações antes de publicar?">
    Sim. O plugin executa `validate_post` para simular seu conteúdo contra as regras de cada rede — tamanho, formato e requisitos de mídia — antes de publicar, para que você capture rejeições evitáveis de antemão.
  </Accordion>

  <Accordion title="Ele pergunta antes de publicar nas minhas contas ao vivo?">
    Sim. Um hook `PreToolUse` de confirmação pede sua aprovação antes de qualquer ação de publicar ou enviar: `create_post`, `update_post`, `retry_post`, `add_comment`, `reply_comment`, `send_message` e `set_auto_response`.
  </Accordion>

  <Accordion title="O plugin consegue combinar com a voz da minha marca?">
    Sim. A skill `draft-in-brand-voice` lê seu histórico de publicações para redigir novo texto em uma voz de marca consistente. Ela produz apenas rascunhos — nada é publicado sem sua confirmação.
  </Accordion>

  <Accordion title="Posso ler análises para orientar a próxima publicação?">
    Sim. As tools de análises retornam métricas por publicação e no nível da conta, então você pode ler os resultados e deixá-los guiar sua próxima publicação.
  </Accordion>

  <Accordion title="O que preciso para usar o plugin?">
    Uma API Key da Ayrshare (uma chave do Business Plan para profiles e sub-profiles) e o Claude Code. Configure a chave com `/ayrshare:setup` ou pela variável de ambiente `AYRSHARE_API_KEY`, depois reinicie o Claude Code.
  </Accordion>

  <Accordion title="Publicar no X/Twitter precisa de configuração extra?">
    Sim. O X/Twitter exige suas próprias credenciais OAuth 1.0a, adicionadas como dois headers de conexão (`X-Twitter-OAuth1-Api-Key` e `X-Twitter-OAuth1-Api-Secret`). Veja [Credenciais BYO do X/Twitter](#xtwitter-byo-credentials) acima.
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Conectar e Configurar" icon="plug" href="/additional/mcp-action-connect" horizontal>
    Autenticação, direcionamento de profile e credenciais BYO.
  </Card>

  <Card title="Catálogo de Tools" icon="list" href="/additional/mcp-action-tools" horizontal>
    As 27 tools agrupadas por domínio, com escopo e propósito.
  </Card>
</CardGroup>