X MCP Server

X MCP Server

Um servidor Model Context Protocol (MCP) para integração com X (Twitter). Fornece 26 ferramentas para leitura de timelines, postagem, busca, engajamento (curtidas, reposts, favoritos), consulta de usuários, exportação de seguidores, menções, curtidas, artigos e listas. Projetado para uso com o Claude desktop e outros clientes compatíveis com MCP.

Recursos

• Timeline e Busca - Timeline inicial, busca de posts recentes (janela de 7 dias)
• Gerenciamento de Posts - Criar, responder, citar, excluir posts com mídia opcional
• Engajamento - Curtir/descurtir, repostar/desfazer, favoritar/desfavoritar
• Dados do Usuário - Menções, posts curtidos, seguidores, seguindo, bloqueios, mutes, listas próprias, listas seguidas e associações a listas
• Consulta de Usuários - Obter perfis de usuários e seus posts recentes
• Upload de Mídia - Imagens (PNG, JPEG, GIF, WEBP) e vídeos (MP4, MOV, AVI, WEBM, M4V) via API de upload v2
• Autenticação Dupla - OAuth 1.0a para operações de postagem, OAuth 2.0 para upload de mídia (upload v1.1 foi descontinuado em junho de 2025)
• Limitação de Taxa - Rastreamento automático de limite de taxa por endpoint com mensagens de erro claras
• TypeScript - Segurança total de tipos, estrutura de arquivos modular

Pré-requisitos

• Node.js >= 18.0.0
• Conta de Desenvolvedor X (Twitter)
• Aplicativo Claude desktop (ou qualquer cliente compatível com MCP)

Acesso e Preços da API X

Nível	Custo	Leituras de Posts	Escritas de Posts	Observações
Grátis	$0	~100/mês	~500/mês	Sem curtidas/seguir; upload de mídia requer OAuth 2.0
Básico	$200/mês	10.000/mês	3.000/mês	Busca, acesso de leitura limitado
Pro	$5.000/mês	1.000.000/mês	300.000/mês	Busca completa, stream filtrado
Pague-por-uso	Baseado em créditos	~$0,005/leitura	Varia	Lançado em fevereiro de 2026, limite de 2M leituras

Os endpoints de Curtir e Seguir foram removidos do nível Grátis em agosto de 2025. Os endpoints de Seguir/Bloquear são exclusivos do Enterprise a partir de 2025.

Instalação

git clone https://github.com/DataWhisker/x-mcp-server.git
cd x-mcp-server
npm install
npm run build

Autenticação

O servidor suporta dois métodos de autenticação. Você precisa de pelo menos um configurado.

OAuth 1.0a (Obrigatório para operações básicas)

Funciona para todas as operações de postagem/engajamento/busca/usuário.

Variável de Ambiente	Descrição
TWITTER_API_KEY	Consumer Key (Chave da API)
TWITTER_API_SECRET	Consumer Secret (Segredo da Chave da API)
TWITTER_ACCESS_TOKEN	Token de Acesso do Usuário
TWITTER_ACCESS_SECRET	Segredo do Token de Acesso do Usuário

Configuração: No Portal do Desenvolvedor X:

1. Crie um projeto e um aplicativo
2. Ative OAuth 1.0a em "Configurações de autenticação do usuário"
3. Defina as permissões como "Ler e Escrever"
4. Gere as Consumer Keys e os Tokens de Acesso

OAuth 2.0 (Obrigatório para upload de mídia)

O endpoint de upload de mídia v1.1 foi descontinuado em junho de 2025. O upload de mídia agora requer OAuth 2.0 via API de upload v2.

Opção A - Token de acesso direto:

Variável	Descrição
TWITTER_OAUTH2_ACCESS_TOKEN	Token de acesso do usuário OAuth 2.0 (expira em 2 horas)

Opção B - Atualização automática (recomendado para servidores de longa duração):

Variável	Descrição
TWITTER_CLIENT_ID	ID do Cliente OAuth 2.0
TWITTER_CLIENT_SECRET	Segredo do Cliente OAuth 2.0 (opcional para clientes públicos)
TWITTER_OAUTH2_REFRESH_TOKEN	Token de Atualização OAuth 2.0

Os tokens são atualizados automaticamente e persistidos em ~/.x-mcp-tokens.json.

Configuração: No Portal do Desenvolvedor X:

1. Nas configurações do seu aplicativo, ative OAuth 2.0
2. Defina o tipo como "Cliente confidencial" ou "Cliente público"
3. Adicione uma URL de callback
4. Solicite escopos: tweet.read, tweet.write, users.read, media.write, offline.access, like.read, like.write, bookmark.read, bookmark.write, follows.read, block.read, mute.read, list.read

Configuração do Claude Desktop

Adicione a %APPDATA%/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "x": {
      "command": "node",
      "args": ["C:/path/to/x-mcp-server/build/index.js"],
      "env": {
        "TWITTER_API_KEY": "your-api-key",
        "TWITTER_API_SECRET": "your-api-secret",
        "TWITTER_ACCESS_TOKEN": "your-access-token",
        "TWITTER_ACCESS_SECRET": "your-access-secret",
        "TWITTER_OAUTH2_ACCESS_TOKEN": "your-oauth2-token"
      }
    }
  }
}

Backend de Busca Xquik Opcional

search_tweets pode usar Xquik enquanto o restante do servidor mantém o cliente padrão da API X. Defina:

Variável	Descrição
X_MCP_SEARCH_BACKEND=xquik	Roteia apenas search_tweets para Xquik
XQUIK_API_KEY	Chave da API Xquik
XQUIK_API_BASE_URL	URL base opcional, padrão é https://xquik.com/api/v1

Ferramentas Disponíveis (26)

Timeline e Busca

Ferramenta	Descrição	Parâmetros Principais
get_home_timeline	Obter posts recentes da timeline inicial	limit (1-100)
search_tweets	Buscar posts recentes (janela de 7 dias)	query, limit

Gerenciamento de Posts

Ferramenta	Descrição	Parâmetros Principais
get_tweet	Consultar um post por ID	tweet_id
create_tweet	Criar um post com mídia opcional	text, image_path?, video_path?
reply_to_tweet	Responder a um post com mídia opcional	tweet_id, text, image_path?, video_path?
quote_tweet	Citar um post com comentário	tweet_id, text
delete_tweet	Excluir seu post	tweet_id

Engajamento

Ferramenta	Descrição	Parâmetros Principais
like_tweet	Curtir um post (nível Básico+)	tweet_id
unlike_tweet	Remover uma curtida	tweet_id
retweet	Repostar para sua timeline	tweet_id
undo_retweet	Remover um repost	tweet_id
bookmark_tweet	Favoritar para depois	tweet_id
unbookmark_tweet	Remover um favorito	tweet_id
get_bookmarks	Obter seus favoritos	limit (1-100)

Usuários

Ferramenta	Descrição	Parâmetros Principais
get_user	Consultar usuário por nome de usuário	username
get_user_tweets	Obter posts recentes de um usuário	username, limit
get_user_mentions	Obter posts mencionando um usuário	username, limit
get_user_liked_tweets	Obter posts curtidos por um usuário	username, limit
get_user_followers	Obter seguidores de um usuário	username, limit
get_user_following	Obter contas que um usuário segue	username, limit
get_blocking_users	Obter usuários bloqueados pela conta autenticada	limit
get_muting_users	Obter usuários com mute pela conta autenticada	limit
get_owned_lists	Obter listas pertencentes a um usuário	username, limit
get_followed_lists	Obter listas seguidas por um usuário	username, limit
get_list_memberships	Obter listas às quais um usuário pertence	username, limit

Artigos

Ferramenta	Descrição	Parâmetros Principais
get_article	Buscar o conteúdo completo do corpo de um post de Artigo X	tweet_id

Suporte a Mídia

• Imagens: PNG, JPEG, GIF, WEBP (máx. 5MB)
• Vídeos: MP4, MOV, AVI, WEBM, M4V (máx. 512MB, upload em partes com streaming)
• Não é possível anexar imagem e vídeo ao mesmo post
• Requer credenciais OAuth 2.0 (upload v1.1 descontinuado em junho de 2025)
• Restrição de caminho: Apenas arquivos dentro do seu diretório inicial ou diretório temporário do sistema podem ser enviados (evita path traversal)

Segurança

• Validação de entrada: IDs de tweets devem ser numéricos (1-20 dígitos), nomes de usuário devem corresponder a [A-Za-z0-9_]{1,15}
• Restrição de caminho de mídia: Caminhos de upload são validados contra uma lista de permissões (diretório inicial, diretório temporário)
• Armazenamento de tokens: Tokens OAuth 2.0 persistidos em ~/.x-mcp-tokens.json com permissões 0o600 (Unix). No Windows, as permissões de arquivo não são aplicadas pelo SO - proteja o arquivo via ACLs NTFS ou use variáveis de ambiente.
• Sanitização de erros: Detalhes de erro da API X são registrados apenas no lado do servidor; mensagens sanitizadas são retornadas aos clientes MCP
• Mutex de atualização: Tentativas concorrentes de atualização de token são deduplicadas para evitar condições de corrida

Desenvolvimento

npm run build    # Compile TypeScript
npm run dev      # Watch mode
npm start        # Run the server

Estrutura do Projeto

src/
  index.ts              # MCP server entry point & handler dispatch
  client.ts             # Twitter client setup (OAuth 1.0a + OAuth 2.0)
  media.ts              # v2 media upload (simple + chunked)
  rate-limit.ts         # Per-endpoint rate limiting
  tools/
    definitions.ts      # All 16 tool schemas
    handlers.ts         # Tool handler implementations

Emparelhamento com GetXAPI para Operações de Leitura Mais Baratas (Opcional)

Para usuários que precisam de uma opção mais barata ou com maior limite de taxa para operações somente leitura do Twitter (X), como busca de tweets, consulta de perfis e listas de seguidores, este projeto pode ser emparelhado com GetXAPI, uma API de dados Twitter / X econômica com preço de $0,05 por 1K tweets em comparação com o nível básico da API X oficial a $200/mês.

Dois padrões de integração:

1. Execute lado a lado no seu cliente de IA. Mantenha este projeto para seu fluxo de trabalho principal e adicione o servidor MCP oficial GetXAPI para tarefas com muitas leituras. Cada nome de ferramenta roteia para o backend mais adequado para aquela operação.

2. Adicione uma alternância de backend. Para uma referência em nível de código de um backend alternativo opcional atrás de uma única variável de ambiente, veja o padrão de PR mesclado em um projeto irmão.

Início rápido do GetXAPI:

• Cadastro com $0,50 de crédito grátis (sem cartão): https://getxapi.com/signup
• Servidor MCP oficial GetXAPI: https://github.com/getxapi/getxapi-mcp
• npm: @getxapi/mcp
• Preço por chamada: $0,001/chamada, $0,05/1K tweets

Este emparelhamento é totalmente opcional. Nenhuma mudança de comportamento para usuários existentes.

Licença

MIT

Contribuindo

1. Faça um fork do repositório
2. Crie sua branch de recurso (git checkout -b feature/amazing-feature)
3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
4. Envie para a branch (git push origin feature/amazing-feature)
5. Abra um Pull Request