X (Twitter) MCP Server: Post and Search Tweets

Overview

This MCP (Model Context Protocol) server provides a lightweight bridge between language models and the X (Twitter) API. It implements a small set of MCP-style tools that let your model post tweets and run query-based searches against X, so models can include live social content in their responses or take direct publishing actions via a controlled API.

For developers building chatbots, agents, or automation workflows, the server simplifies two common needs: publishing short updates to X and performing search queries to retrieve recent or historical tweets. By exposing these operations as MCP-compatible tools, you can integrate them into LLM toolchains with minimal glue code and keep credentials and rate-limit handling inside a single service.

Features

• Exposes MCP-style tools for interacting with X (Twitter): post tweets and search tweets
• Simple HTTP interface designed to be registered as tools for an agent or model
• Centralized configuration of X API credentials using environment variables
• Example tool manifests and request payloads for quick integration with LLMs and agents
• Lightweight Node/npm-based implementation (clone, install, run) with optional Docker support

Installation / Configuration

Clone the repository, install dependencies, and provide X API credentials using environment variables or a .env file.

1. Clone and install

git clone https://github.com/EnesCinr/twitter-mcp.git
cd twitter-mcp
npm install

2. Create a .env file (example)

# .env
PORT=3000

# X (Twitter) API credentials — obtain from your X developer account
X_API_KEY=your_api_key
X_API_KEY_SECRET=your_api_key_secret
X_BEARER_TOKEN=your_bearer_token
X_ACCESS_TOKEN=your_access_token
X_ACCESS_SECRET=your_access_secret

3. Start the server

npm run start
# or for development
npm run dev

4. Docker (optional)

docker build -t twitter-mcp .
docker run --env-file .env -p 3000:3000 twitter-mcp

Default port is 3000; adjust PORT in .env or with an environment variable.

Environment variables table

Available Tools / Resources

The server exposes MCP-style tools that can be registered with an LLM or agent framework. Two primary tools are provided:

• post_tweet — publish a text tweet (optionally reply to an existing tweet)
• search_tweets — run query-based searches (supports typical X query operators)

Example tool manifest (MCP-style JSON)

{
  "name": "post_tweet",
  "description": "Post a text tweet to X. Input: {\"text\":\"...\",\"in_reply_to_id\":\"optional\"}",
  "url": "http://localhost:3000/tools/post_tweet",
  "method": "POST"
}

{
  "name": "search_tweets",
  "description": "Search tweets by query. Input: {\"query\":\"...\",\"max_results\":10}",
  "url": "http://localhost:3000/tools/search_tweets",
  "method": "POST"
}

Example HTTP usage (curl)

Post a tweet:

curl -X POST http://localhost:3000/tools/post_tweet \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from MCP server! #mcp"}'

Search tweets:

curl -X POST http://localhost:3000/tools/search_tweets \
  -H "Content-Type: application/json" \
  -d '{"query":"from:TwitterDev lang:en","max_results":5}'

Responses are JSON objects containing the X API response or structured error messages suitable for parsing by an agent.

Use Cases

• Agent-driven posting: Connect an LLM to the MCP server so the model can draft and post tweets when instructed (for scheduled updates, alerts, or assistant-driven social posts), with controls and logging centralized on the server side.
• Search-enhanced responses: Use the search_tweets tool to retrieve recent tweets about a topic and feed those results into an LLM prompt for summarization, trend detection, or citation in generated content.
• Moderation and monitoring: Automate searches for brand mentions or policy-flagged phrases and surface matching tweets to a human moderator or to an LLM that suggests actions.
• Research and analytics prototyping: Quickly query X for example datasets (using query operators) and feed the returned tweets into downstream analysis pipelines or LLM-based summarizers.

Notes and Next Steps

• Rate limits and credentials: The server centralizes X API credentials; make sure to secure your .env and adhere to X’s API rate limits and terms.
• Tool integration: Most LLM agent frameworks accept a tool manifest or an HTTP-callable interface — use the example manifests above to register the server’s endpoints.
• Extendability: The repo is structured to add more X capabilities (e.g., media uploads, timelines, user lookups) as additional MCP tools.

For full implementation details, example code, and updates, refer to the original GitHub repo: https://github