X (Twitter)

Servidor MCP aprimorado para Twitter/X com suporte a OAuth 2.0, uploads de mídia pela API v2, fallbacks inteligentes para v1.1 e limitação de taxa abrangente. Publique tweets com texto/mídia, pesquise e exclua tweets programaticamente.

GitHub

Documentação

Servidor MCP X - Edição Aprimorada

Um servidor de Protocolo de Contexto de Modelo (MCP) aprimorado para X que adiciona suporte a OAuth 2.0, uploads de mídia via API v2 e limitação abrangente de taxa à implementação original.

✨ Recursos

Publicar Tweets: Crie tweets de texto com anexos de mídia opcionais (imagens, GIFs)
Pesquisar Tweets: Pesquise no X com contagem de resultados personalizável
Excluir Tweets: Remova seus tweets programaticamente
Autenticação Dupla: Suporte para OAuth 1.0a e OAuth 2.0
Upload de Mídia: Publique imagens usando a versão apropriada da API para cada método de autenticação
Limitação de Taxa: Proteção integrada para os limites da API do X
Segurança de Tipos: Implementação completa em TypeScript com validação Zod

🔄 Tratamento de Versões da API

Este servidor usa de forma inteligente diferentes versões da API do X com base no método de autenticação e na operação:

OAuth 1.0a

Operações de Tweet: Usa endpoints da API v2
Upload de Mídia: Usa endpoint v1.1 (upload.twitter.com)
Fallback de Exclusão: Alterna automaticamente para v1.1 quando v2 falha

OAuth 2.0

Todas as operações: Usa exclusivamente endpoints da API v2
Upload de Mídia: Usa endpoint v2 (api.x.com/2/media/upload)
Sem acesso v1.1: Não é possível alternar para v1.1 devido a restrições de autenticação

Por que Endpoints Diferentes?

v1.1: API legada, sendo descontinuada, mas ainda funciona com OAuth 1.0a
v2: API moderna com melhores recursos, mas alguns endpoints têm problemas
Mídia: Tokens OAuth 2.0 não podem acessar endpoints de mídia v1.1, devem usar v2
Exclusão: O endpoint de exclusão v2 atualmente tem problemas (erros 500), v1.1 funciona como fallback

📋 Pré-requisitos

Antes de começar, você precisará de:

Uma Conta de Desenvolvedor X (cadastre-se em developer.x.com)
Um Aplicativo X criado no Portal do Desenvolvedor
Credenciais da API (configuração detalhada abaixo)
Node.js 18+ instalado

🔐 Configuração de Autenticação

Este servidor suporta dois métodos de autenticação. Escolha com base nas suas necessidades:

OAuth 1.0a: Configuração mais simples, funciona com todos os recursos, incluindo fallbacks v1.1
OAuth 2.0: Autenticação moderna, necessária para alguns recursos mais recentes

Configurando Seu Aplicativo X

Crie uma Conta de Desenvolvedor:
- Acesse developer.x.com
- Entre com sua conta do Twitter
- Solicite acesso de desenvolvedor se ainda não tiver
Crie um Novo Aplicativo:
- Navegue até o Portal do Desenvolvedor do Twitter
- Clique em "Projetos e Aplicativos" → "Novo Projeto"
- Dê um nome ao seu projeto
- Selecione seu caso de uso
- Crie um novo Aplicativo dentro do projeto
Configure as Permissões do Aplicativo:
- Nas configurações do seu aplicativo, vá para "Configurações de autenticação do usuário"
- Clique em "Configurar"
- Ative OAuth 1.0a e/ou OAuth 2.0
- Defina as permissões do aplicativo como "Leitura e escrita"
- Adicione URLs de callback:
  - Para OAuth 1.0a: http://localhost:3000/callback
  - Para OAuth 2.0: http://localhost:3000/callback
- Defina a URL do site (pode ser seu repositório GitHub)

Configuração OAuth 1.0a

Obtenha Suas Credenciais:
- Na aba "Chaves e tokens" do seu aplicativo
- Copie sua Chave de API e Segredo da Chave de API
- Gere Token de Acesso e Segredo (clique em "Gerar")
- Certifique-se de que o token de acesso tenha permissões de "Leitura e Escrita"

Credenciais Necessárias:

API_KEY=your_api_key_here
API_SECRET_KEY=your_api_secret_key_here
ACCESS_TOKEN=your_access_token_here
ACCESS_TOKEN_SECRET=your_access_token_secret_here

Configuração OAuth 2.0

Obtenha Suas Credenciais de Cliente:
- Na aba "Chaves e tokens" do seu aplicativo
- Encontre o ID do Cliente OAuth 2.0 e o Segredo do Cliente
- Salve-os para o próximo passo
Gere Tokens de Usuário:

Opção A - Use nosso script auxiliar:
```
# Clone this repository first
git clone https://github.com/mbelinky/x-mcp-server.git
cd x-mcp-server/twitter-mcp
npm install

# Run the OAuth2 setup script
node scripts/oauth2-setup.js
```
Opção B - Configuração manual:
- Use o fluxo OAuth 2.0 com PKCE
- Escopos necessários: tweet.read, tweet.write, users.read, media.write, offline.access
- Troque o código de autorização por token de acesso

Credenciais Necessárias:

AUTH_TYPE=oauth2
OAUTH2_CLIENT_ID=your_client_id_here
OAUTH2_CLIENT_SECRET=your_client_secret_here
OAUTH2_ACCESS_TOKEN=your_access_token_here
OAUTH2_REFRESH_TOKEN=your_refresh_token_here

🚀 Instalação

Para Claude Desktop

Instale via NPM (Recomendado):

Edite o arquivo de configuração do Claude Desktop:

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

Adicione esta configuração:

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@mbelinky/x-mcp-server"],
      "env": {
        "API_KEY": "your_api_key_here",
        "API_SECRET_KEY": "your_api_secret_key_here",
        "ACCESS_TOKEN": "your_access_token_here",
        "ACCESS_TOKEN_SECRET": "your_access_token_secret_here"
      }
    }
  }
}

Para OAuth 2.0:

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@mbelinky/x-mcp-server"],
      "env": {
        "AUTH_TYPE": "oauth2",
        "OAUTH2_CLIENT_ID": "your_client_id",
        "OAUTH2_CLIENT_SECRET": "your_client_secret",
        "OAUTH2_ACCESS_TOKEN": "your_access_token",
        "OAUTH2_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Instale a partir do Código-Fonte:

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

Em seguida, atualize sua configuração para apontar para a instalação local:

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "node",
      "args": ["/path/to/twitter-mcp/build/index.js"],
      "env": {
        // ... your credentials
      }
    }
  }
}

Reinicie o Claude Desktop

Para Claude Code (CLI)

Instale o servidor globalmente e adicione-o ao Claude:

# For OAuth 1.0a
claude mcp add twitter-mcp "npx" "-y" "@mbelinky/x-mcp-server" --scope user \
  --env "API_KEY=your_api_key" \
  --env "API_SECRET_KEY=your_secret_key" \
  --env "ACCESS_TOKEN=your_access_token" \
  --env "ACCESS_TOKEN_SECRET=your_access_token_secret"

# For OAuth 2.0
claude mcp add twitter-mcp "npx" "-y" "@mbelinky/x-mcp-server" --scope user \
  --env "AUTH_TYPE=oauth2" \
  --env "OAUTH2_CLIENT_ID=your_client_id" \
  --env "OAUTH2_CLIENT_SECRET=your_client_secret" \
  --env "OAUTH2_ACCESS_TOKEN=your_access_token" \
  --env "OAUTH2_REFRESH_TOKEN=your_refresh_token"

🛠️ Ferramentas Disponíveis

Após a instalação, o Claude pode usar estas ferramentas:

`post_tweet`

Publique um novo tweet com anexos de mídia e respostas opcionais.

Exemplos de prompts:

"Publique um tweet dizendo 'Olá do Claude!'"
"Tweet esta imagem com a legenda 'Veja esta vista!'" (anexar imagem)
"Responda ao tweet ID 123456789 com 'Ótimo ponto!'"

`search_tweets`

Pesquise tweets com contagem de resultados personalizável (10-100).

Exemplos de prompts:

"Pesquise tweets sobre #MachineLearning"
"Encontre 50 tweets recentes mencionando @ClaudeAI"
"Pesquise tweets sobre tutoriais de TypeScript"

`delete_tweet`

Exclua um tweet pelo seu ID.

Exemplos de prompts:

"Exclua o tweet com ID 1234567890"
"Remova meu último tweet (forneça o ID)"

Nota: Devido a problemas temporários na API do Twitter, OAuth 1.0a usa fallback v1.1 para exclusão.

📸 Notas sobre Upload de Mídia

Ao usar o Claude para publicar tweets com imagens:

Use caminhos de arquivo: Salve sua imagem no disco e forneça o caminho do arquivo
Limitação de Base64: Embora o servidor suporte imagens codificadas em base64, o Claude não pode extrair base64 de imagens coladas
Outros clientes: O suporte a base64 permanece disponível para uso programático e outros clientes MCP

Exemplo de uso:

# ✅ Recommended for Claude
"Post tweet with image at /Users/me/photos/sunset.png"

# ❌ Not currently supported in Claude
"Post this image: [pasting an image directly]"

# ✅ Works programmatically
// In code, you can still use base64
{
  "text": "Hello world!",
  "media": [{
    "data": "iVBORw0KGgoAAAANS...",
    "media_type": "image/png"
  }]
}

🧪 Testes

O projeto inclui testes abrangentes:

# Run all tests
npm test

# Run specific test suites
npm test -- --testNamePattern="OAuth"
npm test -- --testPathPattern="unit"

🔧 Desenvolvimento

Configuração

git clone https://github.com/mbelinky/x-mcp-server.git
cd x-mcp-server/twitter-mcp
npm install

Comandos

npm run build    # Build TypeScript
npm run dev      # Run in development mode
npm test         # Run tests
npm run lint     # Lint code
npm run format   # Format code

Variáveis de Ambiente

Crie um arquivo .env para desenvolvimento local:

# OAuth 1.0a
API_KEY=your_api_key
API_SECRET_KEY=your_api_secret_key
ACCESS_TOKEN=your_access_token
ACCESS_TOKEN_SECRET=your_access_token_secret

# OAuth 2.0 (if using)
AUTH_TYPE=oauth2
OAUTH2_CLIENT_ID=your_client_id
OAUTH2_CLIENT_SECRET=your_client_secret
OAUTH2_ACCESS_TOKEN=your_access_token
OAUTH2_REFRESH_TOKEN=your_refresh_token

# Optional
DEBUG=true  # Enable debug logging

✅ Suporte a Upload de Mídia OAuth 2.0

Uploads de mídia agora funcionam com OAuth 1.0a e OAuth 2.0!

OAuth 1.0a usa o endpoint de upload de mídia v1.1 ✓
OAuth 2.0 usa o endpoint de upload de mídia v2 ✓
Ambos os métodos de autenticação suportam publicação de tweets com imagens (JPEG, PNG, GIF)

Nota: OAuth 2.0 requer o escopo media.write para uploads de mídia.

⚠️ Problemas Conhecidos

Exclusão de Tweets (Temporário)

O endpoint de exclusão v2 do Twitter está atualmente com problemas (retornando erros 500). O servidor MCP lida com isso de forma elegante:

OAuth 1.0a: Alterna automaticamente para o endpoint de exclusão v1.1 ✅
OAuth 2.0: Não pode usar o endpoint v1.1, mostrará mensagem de erro útil ⚠️

Este é um problema temporário da API do Twitter. Uma vez resolvido, ambos os métodos de autenticação usarão a exclusão v2.

🐛 Solução de Problemas

Problemas Comuns

"Não foi possível autenticar você"

Verifique se todas as credenciais estão corretas
Confirme que seu aplicativo tem permissões de "Leitura e Escrita"
Para OAuth 1.0a, regenere seus tokens de acesso
Para OAuth 2.0, garanta que os tokens tenham os escopos necessários

"Limite de taxa excedido"

O Twitter tem limites de taxa rigorosos (especialmente no nível gratuito)
Aguarde 15 minutos e tente novamente
Considere atualizar seu nível de acesso à API do Twitter

"Falha no upload de mídia"

Verifique o tamanho do arquivo (máx. 5MB para imagens)
Verifique o formato do arquivo (apenas JPEG, PNG, GIF)
Para OAuth 2.0, garanta que o escopo media.write esteja incluído

"403 Proibido"

Seu aplicativo pode não ter as permissões necessárias
Verifique as configurações do seu Portal do Desenvolvedor do Twitter
Garanta que seu nível de acesso suporte a operação

Modo de Depuração

Ative o registro detalhado definindo a variável de ambiente DEBUG:

{
  "env": {
    "DEBUG": "true",
    // ... other credentials
  }
}

Locais de Registro

Windows: %APPDATA%\Claude\logs\mcp-server-twitter.log
macOS: ~/Library/Logs/Claude/mcp-server-twitter.log

📚 Recursos

🤝 Contribuições

Contribuições são bem-vindas! Por favor:

Faça um fork do repositório
Crie uma branch de recurso
Adicione testes para novas funcionalidades
Garanta que todos os testes passem
Envie um pull request

🔒 Política de Privacidade

Este servidor MCP:

Não armazena nenhum dado do usuário: Todas as credenciais da API do Twitter/X são armazenadas localmente na sua máquina
Não registra informações sensíveis: Chaves de API e tokens nunca são registrados
Comunica-se apenas com Twitter/X: Nenhum dado é enviado a serviços de terceiros
Processa dados localmente: Todas as operações acontecem na sua máquina
Respeita limites de taxa: Proteção integrada para os limites da API do Twitter

Seus tweets, pesquisas e mídias permanecem privados entre você e Twitter/X.

📧 Suporte

E-mail: mbelinky@gmail.com
Problemas: Issues do GitHub
Documentação: Wiki do GitHub

Para vulnerabilidades de segurança, envie e-mail diretamente em vez de criar um issue público.

📄 Licença

MIT

🙏 Agradecimentos

Este é um fork aprimorado de @enescinar/twitter-mcp que adiciona:

Suporte a autenticação OAuth 2.0
Upload de mídia via API v2 do Twitter/X para OAuth 2.0
Fallback automático v1.1 para OAuth 1.0a
Limitação abrangente de taxa para o nível gratuito
Tratamento de erros e depuração aprimorados
Script programático de geração de tokens OAuth 2.0

Implementação original por @enescinar