Twitter Search MCP

A self-hosted MCP server for searching X/Twitter content through Twitee, the official X API, or both. It is licensed under MIT.

Start locally with the Twitee default:

make setup
make dev

Connect an MCP client to http://127.0.0.1:3000/mcp. The canonical endpoint is always /mcp, including Vercel deployments. It accepts POST and OPTIONS; GET /mcp and DELETE /mcp return 405. There is no /sse endpoint. Use GET /healthz for liveness and GET /readyz for readiness.

make setup creates mcp.config.yaml from the credential-free example only when it is absent. Keep that private YAML out of Git.

Providers and tools

Twitee is the default in the example configuration, not a privileged architecture path. A call uses exactly one provider: it never attempts a fallback to another provider and never merges results. When a provider is omitted, the configured default is used. An explicit different provider is accepted only when allow_provider_override is true. When allow_provider_override is false, an explicit different provider is rejected; it is never changed to the default or another provider. An X-only deployment does not advertise search_profiles.

See provider details and architecture for the contract, including opaque cursors bound to the tool, provider, and query.

Related MCP server: X MCP Server

Configuration

Configuration is strict YAML in mcp.config.yaml. Tokens are read directly from that file in v1; environment-variable interpolation is not supported. At least one provider must be enabled, the default provider must be enabled, X requires a bearer token when enabled, and bearer MCP access requires a token.

Twitee-only

This is the local default. Copy mcp.config.example.yaml or use make setup and retain its Twitee section. Set allow_provider_override: false if clients must not select another enabled provider.

search:
  default_provider: twitee
  allow_provider_override: true
providers:
  twitee:
    enabled: true
    base_url: https://twitee.co
    token: ""
  x:
    enabled: false
    base_url: https://api.x.com
    token: ""

X-only

Use a deployment-owned X bearer token. X supports search_posts and exact-handle lookup_profile; it does not support fuzzy search_profiles.

search:
  default_provider: x
  allow_provider_override: false
providers:
  twitee:
    enabled: false
    base_url: https://twitee.co
    token: ""
  x:
    enabled: true
    base_url: https://api.x.com
    token: REPLACE_WITH_X_BEARER_TOKEN

Dual-provider

Enable both providers, keep Twitee as the default, and let clients opt into X explicitly.

search:
  default_provider: twitee
  allow_provider_override: true
providers:
  twitee:
    enabled: true
    base_url: https://twitee.co
    token: ""
  x:
    enabled: true
    base_url: https://api.x.com
    token: REPLACE_WITH_X_BEARER_TOKEN

access.mode is either anonymous or bearer. Bearer access uses one shared, deployment-owned MCP token. The example personal, team, and public files contain no credentials.

Run and verify

make dev
make doctor
npm run doctor -- --connectivity
npm run smoke-mcp -- --url http://127.0.0.1:3000/mcp
npm run smoke-mcp -- --url http://127.0.0.1:3000/mcp --tool search_posts --input '{"query":"MCP","limit":1}'

make doctor validates local configuration without calling providers. --connectivity is opt-in and sends only a HEAD request to each configured provider base URL. The smoke client lists tools by default; its optional sample call uses a small, safe input but may contact the configured upstream provider. Add --bearer <token> for bearer-protected deployments.

Deployment

Cloudflare Workers and Node/Docker are Tier 1 paths. Kubernetes and Vercel are Tier 2 templates. Use the documented commands rather than copying generated output:

The published Node package supports Node.js 20 and newer. Cloudflare generation and deployment use development-only Agents/Wrangler tooling and require Node.js 22.

make deploy-cloudflare
# With Cloudflare rate limiting enabled:
make deploy-cloudflare CLOUDFLARE_RATE_LIMIT_NAMESPACE_ID=1001
make docker-build
make docker-run
make deploy-k8s KUBE_CONTEXT=<context>
make deploy-vercel

The deploy targets run checks and diagnostics first. Read Cloudflare, Docker, Kubernetes, and Vercel before deploying.

Rate limiting

Rate limiting is an abuse/burst guard, not quota or global accounting.

Enable it with a 10s or 1m window in mcp.config.yaml. Cloudflare requires the generated MCP_RATE_LIMITER binding and an explicit CLOUDFLARE_RATE_LIMIT_NAMESPACE_ID; generation refuses missing or placeholder namespaces when rate limiting is enabled.

Token handling

The ignored mcp.config.yaml can contain access and provider tokens. Cloudflare and Vercel run npm run generate:config, which embeds that complete configuration in .generated/config.ts and .generated/wrangler.jsonc; those generated artifacts contain tokens too. Do not commit, publish, upload, log, or share either the private YAML or generated artifacts. If one leaks, rotate the affected token immediately. See SECURITY.md.

Contributing and status

Run make check before opening a contribution. CONTRIBUTING.md explains the local workflow; CODE_OF_CONDUCT.md sets community expectations; CHANGELOG.md records release notes.

This project is not affiliated with, endorsed by, or sponsored by X Corp or Twitee. X and Twitter are used here only to describe compatible services and APIs.