X (Twitter)

Servidor MCP do X (Twitter)

Um servidor Model Context Protocol (MCP) para interagir com o Twitter (X) por meio de ferramentas de IA. Este servidor permite buscar tweets, publicar tweets, pesquisar no Twitter, gerenciar seguidores e muito mais, tudo por meio de comandos em linguagem natural em Ferramentas de IA.

Recursos

• Buscar perfis de usuários, seguidores e listas de seguidos.
• Publicar, excluir e favoritar tweets.
• Pesquisar no Twitter por tweets e tendências.
• Gerenciar favoritos e timelines.
• Tratamento integrado de limite de taxa para a API do Twitter.
• Usa a API v2 do Twitter com autenticação adequada (chaves e tokens de API), evitando o hack de usuário/senha para minimizar o risco de suspensões de conta.
• Fornece uma implementação completa dos endpoints da API v2 do Twitter para gerenciamento de usuários, gerenciamento de tweets, timelines e funcionalidade de pesquisa.

Pré-requisitos

• Python 3.10 ou superior: Garanta que o Python esteja instalado no seu sistema.
• Conta de Desenvolvedor do Twitter: Você precisa de credenciais de API (API Key, API Secret, Access Token, Access Token Secret e Bearer Token) do Portal do Desenvolvedor do Twitter.
• Opcional: Claude Desktop: Baixe e instale o aplicativo Claude Desktop no site da Anthropic.
• Opcional: Node.js (para integração MCP): Necessário para executar servidores MCP no Claude Desktop.
• Um gerenciador de pacotes como uv ou pip para dependências Python.

Instalação

Opção 1: Instalação via Smithery (Recomendado)

Para instalar o servidor MCP do X (Twitter) para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @rafaljanicki/x-twitter-mcp-server --client claude

Opção 2: Instalar do PyPI

A maneira mais fácil de instalar o x-twitter-mcp é via PyPI:

pip install x-twitter-mcp

Opção 3: Instalar a partir do código-fonte

Se você preferir instalar a partir do repositório de código-fonte:

1. Clone o Repositório:

   git clone https://github.com/rafaljanicki/x-twitter-mcp-server.git
   cd x-twitter-mcp-server
   

2. Configure um Ambiente Virtual (opcional, mas recomendado):

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Instale as Dependências: Usando uv (recomendado, pois o projeto usa uv.lock):

   uv sync
   

   Alternativamente, usando pip:

   pip install .
   

4. Configure as Variáveis de Ambiente:

   • Crie um arquivo .env na raiz do projeto (você pode copiar .env.example se fornecido).
   • Adicione suas credenciais da API do Twitter:

     TWITTER_API_KEY=your_api_key
     TWITTER_API_SECRET=your_api_secret
     TWITTER_ACCESS_TOKEN=your_access_token
     TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret
     TWITTER_BEARER_TOKEN=your_bearer_token
     

   • Para usar as ferramentas de favoritos (get_bookmarks, delete_all_bookmarks), adicione também um token de acesso de usuário OAuth 2.0:

     TWITTER_OAUTH2_USER_ACCESS_TOKEN=your_oauth2_user_token
     

     Veja Obtendo um Token de Usuário OAuth 2.0 abaixo.

Obtendo um Token de Usuário OAuth 2.0

Os endpoints de favoritos (GET /2/users/:id/bookmarks, DELETE /2/users/:id/bookmarks/:tweet_id) exigem Contexto de Usuário OAuth 2.0 — eles rejeitam tanto tokens de portador somente para aplicativos quanto OAuth 1.0a. Você precisa executar o fluxo de autorização PKCE uma vez para obter um token com escopo de usuário.

Etapas

1. No Portal do Desenvolvedor do Twitter, abra seu aplicativo → Configurações → Configurações de autenticação de usuário e habilite o OAuth 2.0. Defina uma URL de retorno de chamada (por exemplo, https://localhost/).

2. Execute o fluxo PKCE usando Tweepy:

import tweepy

handler = tweepy.OAuth2UserHandler(
    client_id="YOUR_CLIENT_ID",       # OAuth 2.0 Client ID (from Developer Portal)
    redirect_uri="https://localhost/",
    scope=["bookmark.read", "bookmark.write", "users.read", "offline.access"],
    client_secret="YOUR_CLIENT_SECRET",  # Optional for public clients
)

print(handler.get_authorization_url())
# Open the URL, authorize, copy the redirected URL, then:
redirected_url = input("Paste redirected URL: ")
token = handler.fetch_token(redirected_url)
print(token["access_token"])

3. Defina o token resultante como TWITTER_OAUTH2_USER_ACCESS_TOKEN no seu ambiente ou arquivo .env.

Executando o Servidor

O transporte preferido é HTTP Streamable. Use uma das seguintes opções:

Recomendado: HTTP Streamable (Docker/Smithery)

Execute o servidor como um serviço HTTP com endpoints HTTP Streamable e SSE.

1. Construa a imagem Docker:

   docker build -t x-twitter-mcp .
   

2. Execute o contêiner (Smithery usa PORT; o padrão aqui é 8081):

   docker run -p 8081:8081 -e PORT=8081 x-twitter-mcp
   

3. Endpoints:

   • HTTP Streamable (JSON-RPC sobre HTTP): POST http://localhost:8081/mcp
   • SSE (Server-Sent Events): GET http://localhost:8081/sse

4. Passe a configuração por solicitação (recomendado no Smithery) via parâmetro de consulta config codificado em base64. Exemplo de JSON de configuração:

   {"twitterApiKey":"...","twitterApiSecret":"...","twitterAccessToken":"...","twitterAccessTokenSecret":"...","twitterBearerToken":"..."}
   

   Codifique e chame initialize:

   CONFIG_B64=$(printf '%s' '{"twitterApiKey":"YOUR_KEY","twitterApiSecret":"YOUR_SECRET","twitterAccessToken":"YOUR_TOKEN","twitterAccessTokenSecret":"YOUR_TOKEN_SECRET","twitterBearerToken":"YOUR_BEARER"}' | base64)
   
   curl -sS -X POST "http://localhost:8081/mcp?config=${CONFIG_B64}" \
     -H 'content-type: application/json' \
     -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"capabilities":{}}}'
   

Observações:

• Um POST / retornará 404; use /mcp para HTTP Streamable e /sse para SSE.
• Quando implantado via Smithery, smithery.yaml é configurado para runtime: container e startCommand.type: http.

HTTP Streamable (Local, sem Docker)

Execute o servidor ASGI diretamente.

Se instalado do PyPI:

python -m x_twitter_mcp.http_server

Se instalado do código-fonte com uv:

uv run python -m x_twitter_mcp.http_server

Os endpoints e o envio de configuração são os mesmos acima.

STDIO Legado (Script CLI)

O projeto também expõe um script CLI STDIO x-twitter-mcp-server para clientes de desktop que esperam STDIO.

Se instalado do PyPI:

x-twitter-mcp-server

Se instalado do código-fonte com uv:

uv run x-twitter-mcp-server

Usando com Claude Desktop

Para usar este servidor MCP com Claude Desktop, você precisa configurar o Claude para conectar-se ao servidor. Siga estas etapas:

Etapa 1: Instale o Node.js

O Claude Desktop usa Node.js para executar servidores MCP. Se você não tiver o Node.js instalado:

• Baixe e instale o Node.js em nodejs.org.
• Verifique a instalação:

  node --version
  

Etapa 2: Localize a Configuração do Claude Desktop

O Claude Desktop usa um arquivo claude_desktop_config.json para configurar servidores MCP.

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Se o arquivo não existir, crie-o.

Etapa 3: Configure o Servidor MCP

Edite claude_desktop_config.json para incluir o servidor x-twitter-mcp. Substitua /path/to/x-twitter-mcp-server pelo caminho real para o diretório do seu projeto (se instalado do código-fonte) ou o caminho para o seu executável Python (se instalado do PyPI).

Se instalado do PyPI:

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "x-twitter-mcp-server",
      "args": [],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "TWITTER_API_KEY": "your_api_key",
        "TWITTER_API_SECRET": "your_api_secret",
        "TWITTER_ACCESS_TOKEN": "your_access_token",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "TWITTER_BEARER_TOKEN": "your_bearer_token",
        "TWITTER_OAUTH2_USER_ACCESS_TOKEN": "your_oauth2_user_token"
      }
    }
  }
}

Se instalado do código-fonte com uv:

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/x-twitter-mcp-server",
        "run",
        "x-twitter-mcp-server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

• "command": "x-twitter-mcp-server": Usa o script CLI diretamente se instalado do PyPI.
• "env": Se instalado do PyPI, você pode precisar fornecer variáveis de ambiente diretamente na configuração (já que não há arquivo .env). Se instalado do código-fonte, o arquivo .env será usado.
• "env": {"PYTHONUNBUFFERED": "1"}: Garante que a saída não seja armazenada em buffer para melhor registro no Claude.

Etapa 4: Reinicie o Claude Desktop

• Saia completamente do Claude Desktop.
• Reabra o Claude Desktop para carregar a nova configuração.

Etapa 5: Verifique a Conexão

• Abra o Claude Desktop.
• Procure um ícone de martelo ou conector na área de entrada (canto inferior direito). Isso indica que as ferramentas MCP estão disponíveis.
• Clique no ícone para ver as ferramentas disponíveis do x-twitter-mcp, como post_tweet, search_twitter, get_user_profile, etc.

Etapa 6: Teste com o Claude

Agora você pode interagir com o Twitter usando linguagem natural no Claude Desktop. Aqui estão alguns exemplos de prompts:

• Buscar um Perfil de Usuário:

  Get the Twitter profile for user ID 123456.
  

  O Claude chamará a ferramenta get_user_profile e retornará os detalhes do usuário.

• Publicar um Tweet:

  Post a tweet saying "Hello from Claude Desktop! #MCP"
  

  O Claude usará a ferramenta post_tweet para publicar o tweet e confirmar a ação.

• Pesquisar no Twitter:

  Search Twitter for recent tweets about AI.
  

  O Claude invocará a ferramenta search_twitter e retornará tweets relevantes.

• Obter Tendências:

  What are the current trending topics on Twitter?
  

  O Claude usará a ferramenta get_trends para buscar tópicos em alta.

Quando solicitado, conceda ao Claude permissão para usar as ferramentas MCP para a sessão de chat.

Fluxo de Trabalho Companheiro do OpenClaw

Este servidor MCP é melhor quando um cliente MCP deve chamar ferramentas da API v2 do Twitter diretamente. Se o fluxo de trabalho for executado no OpenClaw e precisar de metadados de instalação de plugins, descoberta de endpoints, alertas de monitoramento, webhooks, sorteios, fluxos de upload ou download de mídia, mensagens diretas, exportação de seguidores ou ações de postagem e resposta com aprovação, use o TweetClaw como um plugin separado do OpenClaw e passe IDs de tweets revisados ou URLs entre as ferramentas.

Veja Fluxo de Trabalho Companheiro do OpenClaw para um fluxo de comandos que mantém as credenciais separadas e evita ações de escrita duplicadas.

Ferramentas Disponíveis

Abaixo está uma lista de todas as ferramentas fornecidas pelo servidor x-twitter-mcp, juntamente com exemplos de execução no Claude Desktop usando prompts em linguagem natural.

Ferramentas de Gerenciamento de Usuários

get_user_profile

• Descrição: Obtenha informações detalhadas do perfil de um usuário.
• Exemplo no Claude Desktop:

  Get the Twitter profile for user ID 123456789.
  

  O Claude retornará os detalhes do perfil do usuário, incluindo ID, nome, nome de usuário, URL da imagem do perfil e descrição.

get_user_by_screen_name

• Descrição: Busca um usuário pelo nome de tela.
• Exemplo no Claude Desktop:

  Get the Twitter user with screen name "example_user".
  

  O Claude retornará os detalhes do perfil do usuário.

get_user_by_id

• Descrição: Busca um usuário pelo ID.
• Exemplo no Claude Desktop:

  Fetch the Twitter user with ID 987654321.
  

  O Claude retornará os detalhes do perfil do usuário.

get_user_followers

• Descrição: Recupera uma lista de seguidores de um determinado usuário.
• Exemplo no Claude Desktop:

  Get the followers of user ID 123456789, limit to 50.
  

  O Claude retornará uma lista de até 50 seguidores.

get_user_following

• Descrição: Recupera usuários que o usuário determinado está seguindo.
• Exemplo no Claude Desktop:

  Who is user ID 123456789 following? Limit to 50 users.
  

  O Claude retornará uma lista de até 50 usuários.

get_user_followers_you_know

• Descrição: Recupera uma lista de seguidores em comum.
• Exemplo no Claude Desktop:

  Get common followers for user ID 123456789, limit to 50.
  

  O Claude retornará uma lista de até 50 seguidores em comum (simulado filtrando seguidores).

get_user_subscriptions

• Descrição: Recupera uma lista de usuários aos quais o usuário especificado está inscrito.
• Exemplo no Claude Desktop:

  Get the subscriptions for user ID 123456789, limit to 50.
  

  O Claude retornará uma lista de até 50 usuários (usando seguindo como proxy para inscrições).

Ferramentas de Gerenciamento de Tweets

post_tweet

• Descrição: Publica um tweet com mídia opcional, resposta e tags.
• Exemplo no Claude Desktop:

  Post a tweet saying "Hello from Claude Desktop! #MCP"
  

  O Claude publicará o tweet e retornará os detalhes do tweet.

delete_tweet

• Descrição: Exclui um tweet pelo seu ID.
• Exemplo no Claude Desktop:

  Delete the tweet with ID 123456789012345678.
  

  O Claude excluirá o tweet e confirmará a ação.

get_tweet_details

• Descrição: Obtém informações detalhadas sobre um tweet específico.
• Exemplo no Claude Desktop:

  Get details for tweet ID 123456789012345678.
  

  O Claude retornará os detalhes do tweet, incluindo ID, texto, data de criação e ID do autor.

create_poll_tweet

• Descrição: Cria um tweet com uma enquete.
• Exemplo no Claude Desktop:

  Create a poll tweet with the question "What's your favorite color?" and options "Red", "Blue", "Green" for 60 minutes.
  

  O Claude criará o tweet com enquete e retornará os detalhes do tweet.

vote_on_poll

• Descrição: Vota em uma enquete.
• Exemplo no Claude Desktop:

  Vote "Blue" on the poll in tweet ID 123456789012345678.
  

  O Claude retornará uma resposta simulada (já que a API v2 do Twitter não suporta votação em enquetes).

favorite_tweet

• Descrição: Favorita um tweet.
• Exemplo no Claude Desktop:

  Like the tweet with ID 123456789012345678.
  

  O Claude favoritará o tweet e confirmará a ação.

unfavorite_tweet

• Descrição: Desfavorita um tweet.
• Exemplo no Claude Desktop:

  Unlike the tweet with ID 123456789012345678.
  

  O Claude desfavoritará o tweet e confirmará a ação.

bookmark_tweet

• Descrição: Adiciona o tweet aos favoritos.
• Exemplo no Claude Desktop:

  Bookmark the tweet with ID 123456789012345678.
  

  O Claude adicionará o tweet aos favoritos e confirmará a ação.

delete_bookmark

• Descrição: Remove o tweet dos favoritos.
• Exemplo no Claude Desktop:

  Remove the bookmark for tweet ID 123456789012345678.
  

  O Claude removerá o favorito e confirmará a ação.

delete_all_bookmarks

• Descrição: DESTRUTIVO E IRREVERSÍVEL. Exclui permanentemente TODOS os favoritos buscando cada página e removendo-os um por um. Requer TWITTER_OAUTH2_USER_ACCESS_TOKEN.
• Exemplo no Claude Desktop:

  Delete all my Twitter bookmarks.
  

  O Claude confirmará com o usuário primeiro, depois excluirá todos os favoritos e relatará a contagem.

get_bookmarks

• Descrição: Recupera os tweets favoritados do usuário autenticado. Retorna até 100 tweets por chamada; use o parâmetro cursor para paginação. Requer TWITTER_OAUTH2_USER_ACCESS_TOKEN.
• Exemplo no Claude Desktop:

  Show my Twitter bookmarks, limit to 25.
  

  O Claude retornará até 25 tweets favoritados, incluindo ID, texto, data de criação e ID do autor.

Ferramentas de Timeline e Pesquisa

get_timeline

• Descrição: Obtém tweets da sua timeline inicial (Para Você).
• Exemplo no Claude Desktop:

  Show my Twitter For You timeline, limit to 20 tweets.
  

  O Claude retornará até 20 tweets da sua timeline Para Você.

get_latest_timeline

• Descrição: Obtém tweets da sua linha do tempo inicial (Seguindo).
• Exemplo no Claude Desktop:

  Show my Twitter Following timeline, limit to 20 tweets.
  

  O Claude retornará até 20 tweets da sua linha do tempo de Seguindo.

search_twitter

• Descrição: Pesquisa no Twitter com uma consulta.
• Exemplo no Claude Desktop:

  Search Twitter for recent tweets about AI, limit to 10.
  

  O Claude retornará até 10 tweets recentes sobre IA.

get_trends

• Descrição: Recupera tópicos em alta no Twitter.
• Exemplo no Claude Desktop:

  What are the current trending topics on Twitter? Limit to 10.
  

  O Claude retornará até 10 tópicos em alta.

get_highlights_tweets

• Descrição: Recupera tweets em destaque da linha do tempo de um usuário.
• Exemplo no Claude Desktop:

  Get highlighted tweets from user ID 123456789, limit to 20.
  

  O Claude retornará até 20 tweets da linha do tempo do usuário (simulados como destaques).

get_user_mentions

• Descrição: Obtém tweets que mencionam um usuário específico.
• Exemplo no Claude Desktop:

  Get tweets mentioning user ID 123456789, limit to 20.
  

  O Claude retornará até 20 tweets que mencionam o usuário.

Solução de Problemas

• Servidor Não Inicia:

  • Certifique-se de que seu arquivo .env tenha todas as credenciais necessárias da API do Twitter (se instalado a partir do código-fonte).
  • Se instalado via PyPI, certifique-se de que as variáveis de ambiente estejam definidas no claude_desktop_config.json ou no seu shell.
  • Verifique a saída do terminal para erros ao executar x-twitter-mcp-server.
  • Verifique se o uv ou o seu executável Python está corretamente instalado e acessível.

• Claude Não Detecta o Servidor:

  • Confirme se o caminho no claude_desktop_config.json está correto.
  • Certifique-se de que o command e o args apontam para o executável e o script corretos.
  • Reinicie o Claude Desktop após atualizar o arquivo de configuração.
  • Verifique os logs do Modo Desenvolvedor do Claude (Ajuda → Ativar Modo Desenvolvedor → Abrir Arquivo de Log do MCP) para erros.

• Erros de Limite de Taxa:

  • O servidor inclui tratamento de limite de taxa, mas se você atingir os limites da API do Twitter, pode ser necessário aguardar a janela de redefinição (por exemplo, 15 minutos para ações de tweets).

• Ferramentas de favoritos retornam 403:

  • get_bookmarks e delete_all_bookmarks exigem TWITTER_OAUTH2_USER_ACCESS_TOKEN. Tokens de portador somente para aplicativos e OAuth 1.0a são rejeitados pelo endpoint de favoritos.
  • Consulte Obtendo um Token de Usuário OAuth 2.0 para instruções de configuração.

• Avisos de Sintaxe:

  • Se você vir mensagens de SyntaxWarning do Tweepy, elas são devidas a problemas de docstring no Tweepy com Python 3.13. O servidor inclui uma supressão de avisos para lidar com isso.

Contribuindo

Contribuições são bem-vindas! Abra uma issue ou envie um pull request no repositório do GitHub.

Licença

Este projeto é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para detalhes.

Autor

• Rafal Janicki - rafal@kult.io