TwitterAPIs MCP
Servidor MCP oficial para twitterapis.com: busca no Twitter/X, usuários, seguidores, tweets, threads, listas, curtidas, favoritos, DMs, além de ações de postar/curtir/retuitar/seguir como ferramentas nativas do Claude/Cursor.
Documentação
@twitterapis/mcp
Servidor oficial do Model Context Protocol para twitterapis.com, a API do Twitter / X como ferramentas nativas para Claude, Cursor, Windsurf e qualquer cliente MCP. Leituras (busca, perfis, timelines, seguidores, DMs) além de ações de escrita (postar, curtir, retweetar, seguir).
Peça ao seu agente para buscar tweets, obter o perfil ou a timeline de um usuário, listar seguidores/seguidos, buscar o contexto de uma thread ou enumerar membros de uma lista, e ele chama a API diretamente. Cada ferramenta mapeia para um endpoint REST em https://api.twitterapis.com; o servidor não mantém estado e encaminha sua chave de API em cada chamada.
Início rápido
Sem necessidade de instalação. Execute com npx. Você precisa de uma coisa: uma chave de API (US$ 0,50 em créditos grátis, sem cartão): twitterapis.com/signup.
Configuração
Claude Desktop
Edite claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"twitterapis": {
"command": "npx",
"args": ["-y", "@twitterapis/mcp@latest"],
"env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
}
}
}
Reinicie o Claude Desktop. As ferramentas twitter_* aparecem no seletor de ferramentas.
Cursor
~/.cursor/mcp.json (ou Settings → MCP → Add New Server):
{
"mcpServers": {
"twitterapis": {
"command": "npx",
"args": ["-y", "@twitterapis/mcp@latest"],
"env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
}
}
}
Windsurf
~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"twitterapis": {
"command": "npx",
"args": ["-y", "@twitterapis/mcp@latest"],
"env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
}
}
}
VS Code (modo Copilot / agente)
.vscode/mcp.json no seu workspace, ou as configurações de MCP no nível do usuário:
{
"servers": {
"twitterapis": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@twitterapis/mcp@latest"],
"env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
}
}
}
Configuração
| Env var | Obrigatório | Padrão | Finalidade |
|---|---|---|---|
TWITTERAPIS_KEY | Sim | (nenhum) | Chave de API do dashboard |
TWITTERAPIS_BASE_URL | Não | https://api.twitterapis.com | Substituir o host da API |
TWITTERAPIS_TIMEOUT_MS | Não | 30000 | Timeout por requisição em milissegundos |
Ferramentas
94 ferramentas: 60 leituras e 34 ações de escrita. A maioria dos endpoints de usuário aceita username (handle sem @) ou user_id (twitter_user_likes e twitter_user_tweets_complete exigem user_id); endpoints de tweet aceitam id ou url; endpoints paginados retornam um cursor que você passa de volta para obter a próxima página. Duas das leituras são consultas gratuitas de conta/cobrança (twitter_account_me, twitter_account_payments); as 14 ferramentas de monitoramento também são gratuitas (administração de conta, não leituras medidas).
Leituras públicas (busca, perfis, tweets, seguidores, curtidas) funcionam apenas com sua chave de API. As leituras somente de conta (bookmarks, DMs, home timeline, seguidores-que-você-conhece) e a maioria das ações de escrita agem COMO uma conta X autenticada, então precisam de uma sessão vinculada à sua chave primeiro (retorna HTTP 409 até então). Vincule uma sessão registrando seus cookies do x.com (twitter_customer_session) ou fazendo login com nome de usuário/senha (twitter_user_login). Alternativamente, passe credenciais inline por chamada em qualquer uma dessas ferramentas (auth_token + ct0, com proxy_url / user_agent opcionais) para agir COMO aquela conta em uma única chamada sem pré-registrar uma sessão, então uma chave de API pode agir como várias contas. Para ações de escrita, defina proxy_url como um proxy residencial, já que o X bloqueia suavemente escritas que saem de IPs de datacenter. Cada ferramenta de escrita é anotada com readOnlyHint: false; ações reversas (excluir, deixar de seguir, descurtir, desfazer retweet, remover bookmark, excluir monitor/webhook) são anotadas com destructiveHint: true para que clientes MCP possam pedir confirmação antes de executá-las. As ferramentas de monitoramento (veja abaixo) são a única exceção: elas administram sua conta twitterapis.com, não uma sessão X, então precisam apenas da sua chave de API, sem sessão vinculada e sem credenciais inline.
Leituras
| Ferramenta | O que faz |
|---|---|
twitter_advanced_search | Buscar tweets com operadores do X (from:, min_faves:, since:, filter:links, etc.) |
twitter_user_search | Encontrar contas de usuário por nome ou palavra-chave |
twitter_user_info | Perfil completo por handle (bio, contagens, verificação, localização) |
twitter_user_info_by_id | Perfil completo por id numérico de usuário |
twitter_user_status | Verifica se uma conta está ativa, suspensa ou excluída |
twitter_user_about | O objeto About estruturado de um usuário (categoria, rótulos profissionais/empresariais, verificação + flags de verificação de identidade, data de entrada e o painel de transparência 'Sobre esta conta' do X) |
twitter_user_affiliates | Contas afiliadas a um perfil de organização |
twitter_check_follow_relationship | Relação de seguir entre dois ids de usuário (quem segue quem) |
twitter_user_tweets | Tweets originais recentes de um usuário (respostas excluídas) |
twitter_user_tweets_and_replies | Timeline completa de um usuário (tweets + respostas) |
twitter_user_tweets_complete | Histórico quase completo de tweets de um usuário em uma única chamada com paginação automática |
twitter_user_media | Imagens e vídeos que um usuário publicou |
twitter_user_mentions | Tweets públicos recentes mencionando um usuário |
twitter_user_likes | Tweets que um usuário curtiu (aba pública de Curtidas) |
twitter_user_followers | Contas que seguem um usuário |
twitter_user_following | Contas que um usuário segue |
twitter_user_followers_v2 | Seguidores com o formato de resposta v2 (campos mais ricos, cursor mais profundo) |
twitter_user_following_v2 | Seguidos com o formato de resposta v2 (campos mais ricos, cursor mais profundo) |
twitter_user_verified_followers | Apenas os seguidores verificados de um usuário |
twitter_followers_you_know | Seguidores de um alvo que sua conta autenticada também segue |
twitter_tweet_detail | Tweet único: texto, autor, métricas, mídia, contexto de citação/resposta |
twitter_tweet_replies | Respostas a um tweet |
twitter_tweet_thread | Thread completa do autor (cadeia de tweets conectados do mesmo autor) |
twitter_tweet_retweeters | Contas que retweetaram um tweet |
twitter_tweet_quotes | Tweets que citam um tweet, com seu texto. Baseado em busca, então count é o que a busca retornou, não o quote_count real do tweet |
twitter_list_members | Membros de uma Lista do Twitter/X |
twitter_list_followers | Contas que seguem uma Lista pública (um conjunto diferente de seus membros) |
twitter_list_tweets | Posts dos membros de uma Lista, baseado em busca: filtrável por data since / until, include_replies e product (Mais recentes / Principais), sem retweets |
twitter_list_timeline | Feed nativo do X de uma Lista: retweets e a ordenação própria do X incluídos, sem filtros, apenas paginação |
twitter_home_timeline | Home timeline da sua conta autenticada (sessão) |
twitter_bookmarks | Bookmarks da sua conta autenticada (sessão) |
twitter_blocking | Contas que sua conta autenticada bloqueou (apenas sua própria lista) (sessão) |
twitter_muting | Contas que sua conta autenticada silenciou (apenas sua própria lista) (sessão) |
twitter_bookmark_search | Busca de texto completo dentro dos seus bookmarks (sessão) |
twitter_bookmark_folders | Pastas de bookmarks da sua conta autenticada (sessão) |
twitter_bookmark_folder_timeline | Tweets dentro de uma das suas pastas de bookmarks, por folder_id (sessão) |
twitter_dm_list | Suas conversas de DM (caixa de entrada), somente leitura (sessão) |
twitter_dm_conversation | Mensagens em uma conversa de DM, somente leitura (sessão) |
twitter_spaces_info | Metadados e lista de participantes de um X Space, ao vivo ou encerrado (por id do Space) |
twitter_community_search | Encontrar Comunidades do X por palavra-chave; a etapa de descoberta que produz o id numérico que o restante da família de comunidades precisa |
twitter_community_info | Uma Comunidade do X por id numérico: nome, contagens, política de entrada, regras, tópico, banners, admin |
twitter_community_about | Moderadores de uma comunidade e uma prévia de membros, cada um retornado como perfil de usuário completo, não o retorno reduzido de linha _members/_moderators |
twitter_community_members | Lista de membros de uma comunidade, cada linha carregando o papel Admin / Moderator / Member daquele membro |
twitter_community_moderators | Moderadores e admins de uma comunidade, a partir de sua própria operação upstream (não um filtro sobre a lista) |
twitter_community_tweets | Timeline de posts de uma comunidade, com o post fixado retornado como seu próprio campo pinned |
twitter_community_memberships | A consulta inversa: todas as comunidades às quais um user_id numérico pertence |
twitter_grok_chat | Pergunte ao Grok do próprio X, fundamentado em dados ao vivo do X, e obtenha a resposta além das fontes que ele citou |
twitter_grok_config | Se a conta autenticada pode usar o Grok e quais modelos ela pode escolher |
twitter_trends | Principais tendências atuais para um local (por country ou woeid) |
twitter_trends_locations | Todos os locais para os quais o X tem tendências, cada um com seu WOEID |
twitter_account_me | Sua conta twitterapis.com: créditos, uso, email (grátis) |
twitter_account_payments | Seu histórico de pagamentos twitterapis.com (grátis) |
twitter_media_status | Estado de processamento de um media_id enviado; faça polling até succeeded antes de anexar vídeo ou GIF (sessão) |
twitter_article_get | Ler o conteúdo completo de um artigo publicado via id/url do tweet de anúncio (público, sem sessão) |
twitter_article_list | Listar seus próprios artigos, filtrados por lifecycle (draft ou published) (sessão) |
Ações de escrita (exigem uma sessão X vinculada)
| Ferramenta | O que faz |
|---|---|
twitter_create_tweet | Publicar um tweet; defina reply_to para responder ou quote para citar tweet |
twitter_delete_tweet | Excluir um dos seus tweets (irreversível) |
twitter_favorite_tweet / twitter_unfavorite_tweet | Curtir / descurtir um tweet |
twitter_retweet / twitter_unretweet | Retweetar / desfazer retweet |
twitter_bookmark_tweet / twitter_unbookmark_tweet | Adicionar bookmark / remover bookmark |
twitter_follow_user / twitter_unfollow_user | Seguir / deixar de seguir um usuário por id |
twitter_dm_send | Enviar uma Mensagem Direta a um usuário pelo recipient_id numérico dele |
twitter_list_create | Criar uma Lista do Twitter/X de propriedade da sua sessão (name, description / is_private opcionais) |
twitter_list_add_member / twitter_list_remove_member | Adicionar / remover uma conta em uma Lista sua; member_count volta como prova de que a escrita foi concluída |
twitter_media_upload | Enviar uma imagem base64, retorna um media_id para twitter_create_tweet |
Artigos (recurso de "Notes" de formato longo do X; escritas exigem uma sessão X vinculada)
| Ferramenta | O que faz |
|---|---|
twitter_article_create | Iniciar um novo artigo em rascunho, retorna seu id |
twitter_article_update_title | Definir o título de um artigo em rascunho ou publicado |
twitter_article_update_cover_media | Anexar uma imagem já enviada como capa de um artigo (media_id de twitter_media_upload) |
twitter_article_update_content | Substituir o corpo de um artigo em rascunho ou publicado (content_state do Draft.js que você constrói) |
twitter_article_publish | Publicar um rascunho, postando um tweet de anúncio público real (não totalmente reversível) |
twitter_article_unpublish | Reverter um artigo publicado para rascunho (mantém o tweet de anúncio no ar) |
twitter_article_delete | Excluir um artigo (rascunho: exclusão definitiva; publicado: despublicar + excluir o tweet de anúncio), irreversível |
Veja também twitter_article_get e twitter_article_list acima.
Monitoramento (entrega por webhook de novos posts; grátis, não medido)
Acompanhe uma conta do X em busca de novos posts e receba-os enviados para seu próprio endpoint HTTPS, assinados com HMAC, em vez de fazer polling. Registre um webhook primeiro, depois crie um monitor; cada novo post de um handle monitorado é entregue a todos os webhooks ativos da sua conta (ou a um subconjunto restrito via webhook_ids). O CRUD de monitor/webhook é administração de conta, não uma leitura medida do Twitter, então todas as ferramentas abaixo são gratuitas.
| Ferramenta | O que faz |
|---|---|
twitter_monitor_create | Comece a monitorar uma conta X (handle) para novas postagens |
twitter_monitor_list | Liste todos os monitores da sua conta |
twitter_monitor_update | Pausar/retomar um monitor ou alterar sua restrição webhook_ids |
twitter_monitor_delete | Parar e remover um monitor (irreversível) |
twitter_monitor_health | Status de um monitor, sinalizador de degradação, intervalo de polling, posição do cursor |
twitter_monitor_account_health | Resumo geral da conta: status do serviço, contagens de monitores ativos/pausados, contagens de resultados de entrega em 24h, em uma única chamada |
twitter_monitor_deliveries | Eventos de entrega recentes em todos os monitores, com latência de detecção + entrega |
twitter_x_user_stream_add_user | Substituto compatível para twitter_monitor_create usando um envelope no formato x_user_stream |
twitter_x_user_stream_remove_user | Substituto compatível para twitter_monitor_delete usando um envelope no formato x_user_stream |
twitter_x_user_stream_list_users | Substituto compatível para twitter_monitor_list usando um envelope no formato x_user_stream |
twitter_monitor_webhook_create | Registre uma URL de entrega HTTPS; retorna o segredo de assinatura HMAC uma vez |
twitter_monitor_webhook_list | Liste todos os webhooks registrados na sua conta |
twitter_monitor_webhook_delete | Excluir suavemente um webhook por id (irreversível do lado do chamador) |
twitter_monitor_webhook_test | Envie um evento de teste assinado para um webhook agora mesmo, de forma síncrona |
Configuração de sessão
Vincule uma conta X à sua chave uma vez, para que as leituras e ações de escrita exclusivas da conta atuem como ela (ou passe auth_token/ct0 por chamada, em vez disso).
| Ferramenta | O que faz |
|---|---|
twitter_customer_session | Registre seus cookies de sessão do x.com (auth_token + ct0) na sua chave |
twitter_customer_session_delete | Revogue essa sessão armazenada, excluindo seu auth_token + ct0 do serviço. Idempotente e gratuito |
twitter_user_login | Faça login com username + password (+ totp_secret para 2FA); armazena a sessão na sua chave. Retorna uma confirmação, nunca os cookies |
Exemplos de uso
Buscar tweets de IA em alta
"Encontre os tweets mais populares sobre agentes de IA publicados esta semana"
O agente chama twitter_advanced_search com:
query: "AI agents min_faves:200 since:2024-01-01"
product: "Top"
count: 20
Obter postagens recentes de um usuário
"Obtenha os últimos 10 tweets de @sama"
O agente chama twitter_user_tweets com:
username: "sama"
count: 10
Ler um thread completo
"Obtenha o thread completo para este tweet: https://x.com/karpathy/status/1849....."
O agente chama twitter_tweet_thread com:
url: "https://x.com/karpathy/status/1849....."
Paginar pelos seguidores
"Liste os primeiros 100 seguidores de @openai, depois os próximos 100"
Primeira chamada, twitter_user_followers: { username: "openai", count: 100 }
Segunda chamada, devolva o cursor da primeira resposta: { username: "openai", count: 100, cursor: "<cursor from response>" }
Monitorar menções à marca
"Mostre-me tweets recentes mencionando @twitterapis"
O agente chama twitter_user_mentions com:
username: "twitterapis"
count: 50
Solução de problemas
HTTP 401 (invalid or missing API key) Verifique se TWITTERAPIS_KEY está configurado corretamente na configuração do seu cliente MCP e corresponde à chave mostrada no seu painel.
HTTP 402 (insufficient credits) Recarregue em twitterapis.com/dashboard. Seus primeiros $0,50 são gratuitos no cadastro.
HTTP 403 (access forbidden) A conta ou o tweet pode ser privado/protegido, ou seu plano não inclui este endpoint.
HTTP 404 (not found) O usuário, tweet ou lista pode ter sido excluído, suspenso, ou o id/handle está errado.
HTTP 429 (rate limited) Aguarde alguns segundos e tente novamente. Se isso ocorrer com frequência, adicione "TWITTERAPIS_TIMEOUT_MS": "60000" à sua configuração de ambiente e espaçe as solicitações em massa.
Request failed: timed out after 30000ms O tempo limite padrão é de 30 s. Para buscas paginadas grandes, defina TWITTERAPIS_TIMEOUT_MS para um valor maior (por exemplo, 60000).
As ferramentas não aparecem no Claude / Cursor Garanta que npx esteja no seu PATH e que o Node.js 18+ esteja instalado (node --version). Verifique os logs do cliente MCP para erros de inicialização.
Preços
Chamadas são cobradas na sua conta twitterapis.com. Quase todos os endpoints custam $0,0008/chamada: todas as leituras (busca, perfis, tweets, seguidores, curtidas) mais as ações de escrita simples (curtir, retweetar, marcar como favorito, seguir e seus desfazimentos, excluir). Na taxa de leitura, isso equivale a $0,04 por 1.000 tweets, já que cada chamada retorna cerca de 20 tweets. Os endpoints premium custam um pouco mais: criação de tweet, envio de DM (twitter_dm_send) e leituras de DM (twitter_dm_list, twitter_dm_conversation) a $0,0016/chamada, histórico completo de tweets (twitter_user_tweets_complete) a $0,0024/chamada, um thread completo de tweets (twitter_tweet_thread) e uma resposta Grok (twitter_grok_chat) a $0,004/chamada, e as escritas de edição de artigo (twitter_article_create, twitter_article_update_title, twitter_article_update_cover_media, twitter_article_update_content, twitter_article_publish, twitter_article_unpublish) a $0,0016/chamada (twitter_article_get, twitter_article_list e twitter_article_delete permanecem no padrão de $0,0008/chamada). Seus primeiros $0,50 são gratuitos. Veja twitterapis.com/pricing.
Links
- Documentação: docs.twitterapis.com
- Painel / chaves de API: twitterapis.com/dashboard
- Preços: twitterapis.com/pricing
- URL base da API REST (chame diretamente, sem MCP):
https://api.twitterapis.com
FAQ
Preciso de uma conta de desenvolvedor X (Twitter)? Não. Obtenha uma chave de API em twitterapis.com/signup; não há etapa de aplicação ou aprovação.
É somente leitura? Não. 60 ferramentas de leitura funcionam apenas com sua chave de API; 34 ações de escrita (postar, curtir, retweetar, seguir, DM, upload de mídia, criar lista/adicionar membro/remover membro, criar/editar/publicar/excluir artigo, criar/atualizar/excluir monitor/webhook) atuam como uma conta X vinculada ou credenciais inline por chamada, exceto CRUD de monitor/webhook, que é administração de conta e precisa apenas da sua chave de API.
Quais clientes são suportados? Claude Desktop, Cursor, Windsurf e VS Code (modo agente Copilot), ou qualquer cliente Model Context Protocol.
Como é cobrado? Por solicitação. Novas chaves começam com $0,50 em créditos gratuitos, sem necessidade de cartão. Veja preços.
Ele armazena minha chave ou dados? Não. O servidor não mantém estado e encaminha sua chave de API em cada chamada.
Mantenedores
src/tools.js é gerado. Não o edite. O catálogo é construído no momento da compilação a partir de duas entradas versionadas:
test/openapi.snapshot.json, uma cópia vendida da especificação OpenAPI publicada, que fornece a estrutura: quais endpoints existem, quais parâmetros cada um aceita, se um parâmetro é obrigatório e seu tipo.scripts/tools.overrides.mjs, escrita manualmente, que fornece tudo o que a especificação não pode expressar: as descrições de ferramentas e argumentos que um modelo lê para decidir como chamar uma ferramenta, as regras entre campos ("forneça exatamente um deusernameouuser_id"), os argumentos de credenciais por chamada que viajam como cabeçalhosx-*, e os sinalizadores de escrita / destrutivo / corpo JSON.
A especificação é vendida de propósito. Nada é buscado no momento da instalação ou na inicialização do servidor, então o pacote publicado é um artefato fixo, em vez de um que depende de um hostname ainda respondendo.
npm run openapi:refresh # re-vendor the spec, prints the route diff
npm run build # regenerate src/tools.js
npm test # gates, incl. "src/tools.js matches the generator"
npm test falha se src/tools.js foi editado manualmente ou deixado desatualizado, se o catálogo e a especificação ao vivo discordarem, ou se a lista de ferramentas e este README discordarem.
Licença
MIT