Skip to main content
Glama


A Model Context Protocol (MCP) server that enables seamless interaction with Twitter/X through AI assistants such as Claude Desktop.

Features

  • ๐Ÿฆ Post Tweets - Share your thoughts with the world

  • ๐Ÿ–ผ๏ธ Image Support - Post tweets with images (JPG, PNG, GIF, WEBP)

  • ๐Ÿ” Search Tweets - Find and analyze tweets by query

  • ๐Ÿ‘ค User Profile Context - Fetch comprehensive user profiles with bio, metrics, pinned tweet, and recent activity

  • ๐Ÿ’ฌ Thread History - Retrieve full conversation threads by tweet ID

  • ๐Ÿ”” Mention Monitoring - Search recent mentions of the authenticated user or custom keywords

  • ๐Ÿงต Smart Threads - Auto-split long content into threaded tweet chains

  • ๐Ÿ’ฌ Quote Tweets - Quote an existing tweet with AI commentary

  • ๐ŸŽฌ Media Extraction - Extract direct media URLs from tweets (images, video, GIF)

  • โค๏ธ Engagement - Like, retweet, or bookmark tweets directly

  • ๐Ÿ”Ž Optional Xquik Search - Use Hermes Tweet/Xquik for read-only search

  • ๐Ÿ’ฌ Reply to Tweets - Engage in conversations

  • ๐Ÿ” Secure Authentication - OAuth 1.0a authentication

  • โšก Rate Limiting - Built-in protection against API limits

Related MCP server: X (Twitter) MCP Server

Why Twitter MCP?

Twitter MCP makes it easy for AI assistants to interact with X (Twitter) through natural language.

Benefits

  • ๐Ÿš€ Zero installation using NPX

  • ๐Ÿค– Works with Claude Desktop and MCP-compatible clients

  • ๐Ÿฆ Post tweets directly from AI conversations

  • ๐Ÿ–ผ๏ธ Upload images with tweets

  • ๐Ÿ” Search Twitter using multiple backends

  • ๐Ÿ” Secure OAuth authentication

  • โšก Built-in rate limiting and validation

  • ๐Ÿ› ๏ธ Open-source and TypeScript powered

Perfect For

  • Content creators

  • Social media managers

  • AI agent developers

  • Marketing teams

  • Researchers and analysts

  • MCP enthusiasts

Table of Contents

Installation

Prerequisites

  • Node.js 18 or higher

  • npm or npx

  • Twitter Developer Account with API credentials

  • Claude Desktop App

Quick Start

The easiest way to use this MCP server is through the interactive installer:

npx @muhammadsiddiq/twitter-mcp

๐Ÿณ Docker / Podman

An official image ships on Docker Hub with the MCP stdio server as its entrypoint. It works identically with both Podman and Docker.

# Docker
docker pull genaiwithms/twitter-mcp:latest

# Podman
podman pull docker.io/genaiwithms/twitter-mcp:latest

The server speaks MCP over stdio (stdin/stdout), so instead of running CLI commands you point your MCP client at the container, or test it directly:

# Smoke test: the server answers an MCP initialize handshake and prints it to stdout
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n' \
  | docker run -i --rm genaiwithms/twitter-mcp:latest

Provide your Twitter credentials with -e for real requests:

docker run -i --rm \
    -e API_KEY="sk-..." \
    -e API_SECRET_KEY="sk-..." \
    -e ACCESS_TOKEN="sk-..." \
    -e ACCESS_TOKEN_SECRET="sk-..." \
    genaiwithms/twitter-mcp:latest

Optional search backends:

    -e XQUIK_API_KEY="..." -e XQUIK_BASE_URL="https://xquik.com" \
    -e GETXAPI_API_KEY="..." -e GETXAPI_BASE_URL="https://api.getxapi.com" \

The container runs as a non-root user (node). Credentials are never baked into the image. post_tweet_with_image reads a local file path, so if you use that tool from the container, mount the image file with -v /abs/path:/abs/path and pass the same path.

From the repository root, tag it for your own Docker Hub namespace:

# Docker
docker build -t <user>/twitter-mcp:0.3.11 .
docker push <user>/twitter-mcp:0.3.11

# Podman
podman build -t docker.io/<user>/twitter-mcp:0.3.11 .
podman login docker.io
podman push docker.io/<user>/twitter-mcp:0.3.11

Configuration

Step 1: Run the installer

Start the setup flow with:

npx @muhammadsiddiq/twitter-mcp

The installer guides you through every question and writes the correct MCP config for the client you choose.

Step 2: Choose your target client

The first prompt asks which AI assistant environment you want to integrate with. Available options are:

  • Claude Desktop App

  • Cursor IDE

  • OpenCode IDE

  • Hermes

  • Kilo

  • Custom Agent

If you choose a built-in client, the installer already knows the right config location and format. If you choose Custom Agent, it asks for the config file path and the config structure to use.

Step 3: Answer the credential prompts

Next, the installer asks for the Twitter/X API credentials it needs to work:

  • Consumer Key

  • Consumer Secret Key

  • Access Token

  • Access Token Secret

These values are required for posting, replying, and Twitter API search.

How to get Twitter API credentials

  1. Visit Twitter Developer Portal

  2. Create a new App or use an existing one

  3. Navigate to "Keys and Tokens"

  4. Generate/Copy the following:

  • Consumer Key

  • Consumer Secret Key

  • Access Token

  • Access Token Secret

Provide these values when the installer prompts for them.

Step 4: Optional search backend keys

The installer then asks whether you want to add optional read-only search backends for search_tweets.

If you say yes, it can collect:

  • XQuik / Hermes Tweet API key

  • GetXAPI API key

These are optional. If you skip them, the server still works with the Twitter OAuth credentials.

Getting an Xquik / Hermes Tweet token

  1. Sign in at dashboard.xquik.com.

  2. Open Account > API Keys.

  3. Create an API key for this MCP server and copy it once.

  4. Store that value as XQUIK_API_KEY in your MCP config or shell environment.

  5. If your deployment uses the Hermes Tweet naming, set the same value as HERMES_TWEET_API_KEY instead.

  6. Leave XQUIK_BASE_URL unset unless your team runs a compatible non-default deployment.

  7. Restart your client and call search_tweets to verify read-only search.

Keep the key out of Git, chat prompts, screenshots, and shared config files. The key only changes search_tweets; posting and replying still use the Twitter OAuth variables.

Getting a GetXAPI token

  1. Sign in at getxapi.com.

  2. Create an API key for this MCP server and copy it once.

  3. Store that value as GETXAPI_API_KEY in your MCP config or shell environment.

  4. Leave GETXAPI_BASE_URL unset unless your team runs a compatible non-default deployment.

  5. Restart your client and call search_tweets to verify read-only search.

Step 5: Finish setup

After the questions are answered, the installer writes the config automatically and tells you to restart the selected client.

Troubleshooting

Can't find Connectors in Settings?

  • Make sure you're using the latest version of Claude Desktop

  • Try restarting the application

Path not working?

  • Use the full absolute path (complete path from root)

  • Avoid spaces in folder names, or use quotes around the path

  • Check that the directory actually exists on your computer

Changes not taking effect?

  • Make sure you completely closed Claude Desktop (check system tray/menu bar)

  • Wait a few seconds before reopening

  • Restart your computer if issues persist

Usage

Once configured, you can interact with Twitter through natural language commands to Claude.

Posting Tweets

Simple Tweet:

Post a tweet: "Hello World! ๐ŸŒ"

Posting with Images

Important: Make sure you have configured the filesystem MCP server as shown in Step 4.

Tweet with Image:

Post this image with caption: "Check out this amazing view!"
take image from desktop

Working with Images

Images must be accessible to the MCP server process that your client launches. Below are the common flows and what to expect:

  • CLI flow (running the server directly):

    • You can pass an absolute or relative path to the image when using the CLI/server directly.

    • Example: npx @muhammadsiddiq/twitter-mcp --stdio then provide /home/me/Pictures/photo.jpg or ./images/photo.jpg when prompted.

    • If the CLI is started from a different working directory, provide an absolute path or change to the correct folder first.

  • Agent flow (Claude Desktop, Cherry Studio, etc.):

    • Most desktop agents use a filesystem MCP connector to grant the agent access to files. Claude Desktop includes this; some clients (e.g., Cherry Studio) require you to enable/configure the filesystem connector.

    • Configure the client's filesystem MCP (or connector) to include the folder(s) containing your images. After granting access, restart the client and then ask the agent to attach or use the image by filename or path.

  • Permission notes:

    • The MCP server process (or the agent) must have read permission for the image file.

    • When using desktop agents, the client will typically prompt you to grant filesystem access; follow the client's permission flow rather than changing file permissions globally.

Supported path examples:

  • Windows: C:\Users\YourName\Pictures\image.jpg

  • macOS: /Users/YourName/Pictures/image.jpg

  • Linux: /home/yourname/pictures/image.jpg

  • Relative: ./images/photo.jpg (relative to the server's working directory)

Supported formats and limits:

  • JPEG/JPG, PNG, GIF, WEBP

  • Max size: ~5MB for static images, ~15MB for animated GIFs (subject to client limits)

Best practices:

  • Use absolute paths if you are unsure of the current working directory.

  • Keep images in a dedicated folder and add that folder to your client's filesystem permissions.

  • Prefer small, optimized images for faster uploads and fewer failures.

  • If an agent cannot see a file, check the client's filesystem connector settings and restart the client after granting access.

If you're using an MCP client not listed here, check the client's documentation for how to grant or configure filesystem access (search for "filesystem connector", "desktop connectors", or "MCP filesystem").

Searching Tweets

Basic Search:

Search for tweets about "artificial intelligence"

Advanced Search:

Search for 50 tweets about "climate change" from the past week

User Profile Lookup

Get profile context:

Look up the profile of "elonmusk"

The tool returns bio, profile metadata, follower/following metrics, pinned tweet, and the 5 most recent original tweets.

Thread History

Get conversation thread:

Show me the full conversation thread for tweet 1234567890

The tool finds the conversation the tweet belongs to and returns all tweets ordered chronologically, with author IDs, text, timestamps, and reply relationships.

Mention Monitoring

Check mentions and search:

What are the latest mentions of my account?
Search recent tweets about "product launch"

Without a query, returns tweets mentioning the authenticated user. With a query, searches recent tweets matching it. Each result includes author, text, timestamp, and engagement metrics.

Smart Thread Publishing

Publish long content as a thread:

Publish this as a thread: "Part 1: Introduction to AI\n\nPart 2: Key Concepts\n\nPart 3: Applications"

Use double newlines to indicate tweet breaks. The tool splits by paragraph, then by sentence if needed (max 280 chars per tweet), and posts them as a connected reply chain.

Quote Tweets

Quote an existing tweet:

Quote tweet 1234567890 with commentary: "This is an interesting perspective!"

The tool posts your commentary as a new tweet with the target tweet embedded as a quote beneath it.

Media Extraction

Extract media from a tweet:

Get the media URLs from tweet 1234567890

Returns direct URLs for all attached images, video variants (with bit rates), and animated GIFs.

Engagement

Interact with a tweet:

Like tweet 1234567890
Retweet the post by user
Bookmark that tweet for later

Supports three actions: like, retweet, and bookmark. Returns a success confirmation.

API Reference

Tools

The server provides the following tools:

1. post_tweet

Post a text-only tweet.

Parameters:

  • text (string) โ€” Tweet content

  • reply_to_tweet_id (string, optional) โ€” ID of a tweet to reply to

2. post_tweet_with_image

Post a tweet with an attached image.

Parameters:

  • text (string) โ€” Tweet content

  • image_path (string) โ€” Local path to image (absolute or relative)

  • reply_to_tweet_id (string, optional) โ€” ID of a tweet to reply to

Supported Image Formats:

  • JPEG/JPG

  • PNG

  • GIF (animated, max 15MB)

  • WEBP

3. get_user_profile_context

Fetch a comprehensive Twitter/X user profile.

Parameters:

  • username (string) โ€” Twitter handle (without @)

Returns:

  • id, name, username, description, profile_image_url

  • verified, protected, location, url, created_at

  • public_metrics (followers/following/tweet/listed counts)

  • pinned_tweet (if set)

  • recent_tweets (last 5 original tweets with engagement metrics)

Example:

// Request:
{
  "username": "elonmusk"
}

// Response:
{
  "status": "success",
  "message": "User profile fetched successfully",
  "data": {
    "id": "44196397",
    "name": "Elon Musk",
    "username": "elonmusk",
    "description": "...",
    "public_metrics": {
      "followers_count": 190000000,
      "following_count": 743,
      "tweet_count": 30000,
      "listed_count": 150000
    },
    "pinned_tweet": {
      "id": "123456789",
      "text": "...",
      "created_at": "2026-06-01T12:00:00.000Z"
    },
    "recent_tweets": [
      {
        "id": "987654321",
        "text": "...",
        "created_at": "2026-06-12T08:00:00.000Z",
        "like_count": 50000,
        "retweet_count": 10000,
        "reply_count": 2000
      }
    ]
  }
}

4. fetch_thread_history

Retrieve the full conversation thread for a tweet.

Parameters:

  • tweet_id (string) โ€” ID of the tweet in the thread

Returns:

  • conversation_id โ€” the thread's conversation ID

  • thread โ€” array of tweets ordered oldest-first with id, text, author_id, created_at, engagement metrics, and in_reply_to_tweet_id

Example:

// Request:
{
  "tweet_id": "1234567890"
}

// Response:
{
  "status": "success",
  "message": "Thread history fetched successfully",
  "data": {
    "conversation_id": "1234567890",
    "thread": [
      {
        "id": "1234567880",
        "text": "Original post...",
        "author_id": "user1",
        "created_at": "2026-06-12T10:00:00.000Z",
        "like_count": 120,
        "retweet_count": 30,
        "reply_count": 5,
        "in_reply_to_tweet_id": null
      },
      {
        "id": "1234567890",
        "text": "Reply to the thread...",
        "author_id": "user2",
        "created_at": "2026-06-12T10:05:00.000Z",
        "like_count": 10,
        "retweet_count": 1,
        "reply_count": 0,
        "in_reply_to_tweet_id": "1234567880"
      }
    ]
  }
}

5. search_recent_mentions

Monitor mentions of the authenticated user or search recent tweets by keyword.

Parameters:

  • query (string, optional) โ€” Custom search query. Omitting returns mentions of your account.

  • max_results (number, optional, default 10) โ€” Results to return (5โ€“100).

Returns:

  • tweets โ€” array with id, text, author_id, author_username, created_at, like_count, retweet_count, reply_count

  • meta โ€” result_count and optional next_token for pagination

Example:

// Request (mentions):
{
  "max_results": 10
}

// Request (custom search):
{
  "query": "product launch",
  "max_results": 20
}

// Response:
{
  "status": "success",
  "data": {
    "tweets": [
      {
        "id": "1234567890",
        "text": "@user Great post!",
        "author_id": "98765",
        "author_username": "follower1",
        "created_at": "2026-06-12T12:00:00.000Z",
        "like_count": 5,
        "retweet_count": 1,
        "reply_count": 0
      }
    ],
    "meta": {
      "result_count": 10
    }
  }
}

6. publish_smart_thread

Split long content into a threaded tweet chain.

Parameters:

  • content (string, 1โ€“10000 chars) โ€” Full text to publish. Use double newlines to indicate tweet breaks.

Returns:

  • thread โ€” array of posted tweets with position, id, text, created_at

  • total_tweets โ€” count of tweets in the thread

  • first_tweet_url โ€” URL to the first tweet on X/Twitter

Example:

// Request:
{
  "content": "Excited to announce our new product!\n\nIt has three key features:\n\nFeature 1: Lightning fast.\n\nFeature 2: Easy to use.\n\nFeature 3: Open source.\n\nCheck it out at example.com!"
}

// Response:
{
  "status": "success",
  "message": "Smart thread published successfully",
  "data": {
    "thread": [
      { "position": 1, "id": "111", "text": "Excited to announce our new product!", "created_at": "..." },
      { "position": 2, "id": "112", "text": "It has three key features:", "created_at": "..." },
      { "position": 3, "id": "113", "text": "Feature 1: Lightning fast.", "created_at": "..." }
    ],
    "total_tweets": 3,
    "first_tweet_url": "https://x.com/i/status/111"
  }
}

7. draft_quote_tweet

Quote an existing tweet with AI commentary.

Parameters:

  • target_tweet_id (string) โ€” ID of the tweet to quote

  • commentary (string, max 280) โ€” Text to display above the quoted tweet

Returns:

  • id, text, author_id, created_at โ€” quote tweet details

  • quoted_tweet_id โ€” the ID of the quoted tweet

  • tweet_url โ€” URL to the quote tweet on X/Twitter

Example:

// Request:
{
  "target_tweet_id": "1234567890",
  "commentary": "This is a great take on the topic!"
}

// Response:
{
  "status": "success",
  "message": "Quote tweet drafted successfully",
  "data": {
    "id": "9876543210",
    "text": "This is a great take on the topic!",
    "author_id": "self",
    "created_at": "2026-06-12T12:00:00.000Z",
    "quoted_tweet_id": "1234567890",
    "tweet_url": "https://x.com/i/status/9876543210"
  }
}

8. media_extraction_helper

Extract direct media URLs from a tweet.

Parameters:

  • tweet_id (string) โ€” ID of the tweet to extract media from

Returns:

  • tweet_id โ€” the source tweet ID

  • media โ€” array of media items, each with type, url, preview_image_url, width, height, duration_ms, and variants (for videos/GIFs)

  • media_count โ€” total count

Example:

// Request:
{
  "tweet_id": "1234567890"
}

// Response:
{
  "status": "success",
  "message": "Media extracted successfully",
  "data": {
    "tweet_id": "1234567890",
    "media": [
      {
        "type": "photo",
        "url": "https://pbs.twimg.com/media/ABC123.jpg",
        "width": 1200,
        "height": 800
      },
      {
        "type": "video",
        "preview_image_url": "https://pbs.twimg.com/media/DEF456.jpg",
        "duration_ms": 30000,
        "width": 1920,
        "height": 1080,
        "variants": [
          {
            "url": "https://video.twimg.com/video.mp4",
            "content_type": "video/mp4",
            "bit_rate": 2000000
          }
        ]
      }
    ],
    "media_count": 2
  }
}

9. engage_with_tweet

Like, retweet, or bookmark a tweet.

Parameters:

  • tweet_id (string) โ€” ID of the tweet to interact with

  • action (enum: "like" | "retweet" | "bookmark") โ€” Action to perform

Returns:

  • tweet_id, action, success (boolean)

Example:

// Request:
{
  "tweet_id": "1234567890",
  "action": "like"
}

// Response:
{
  "status": "success",
  "message": "Engagement action performed successfully",
  "data": {
    "tweet_id": "1234567890",
    "action": "like",
    "success": true
  }
}

10. search_tweets

Search for tweets matching a query.

Set XQUIK_API_KEY or HERMES_TWEET_API_KEY to route search through Hermes Tweet/Xquik. Set GETXAPI_API_KEY to route search through GetXAPI. Without those variables, search uses the configured Twitter API credentials. Types:

interface SearchTweetsRequest {
  query: string;           // Search query string
  count: number;          // Number of results (10-100)
}

interface SearchResponse {
  tweets: Tweet[];
  meta: {
    result_count: number;
    next_token?: string;
  };
}

Example:

// Request:
{
  "query": "machine learning",
  "count": 25
}

// Response:
{
  "status": "success",
  "message": "Search completed successfully",
  "data": {
    "tweets": [
      {
        "id": "1234567891",
        "text": "Exploring machine learning concepts...",
        "author_id": "user123",
        "created_at": "2025-11-06T12:00:00.000Z"
      }
      // ... more tweets
    ],
    "meta": {
      "result_count": 25,
      "next_token": "abc123xyz"
    }
  }
}

Development

Local Development Setup

  1. Clone the repository:

git clone https://github.com/genaiwithms/twitter-mcp.git
cd twitter-mcp
  1. Install dependencies:

npm install
  1. Build the project:

npm run build
  1. Set up environment:

Create a .env file in the project root:

API_KEY=your_api_key
API_SECRET_KEY=your_api_secret
ACCESS_TOKEN=your_access_token
ACCESS_TOKEN_SECRET=your_access_token_secret
  1. Run locally:

Update your Claude config to use local build:

{
  "mcpServers": {
    "twitter": {
      "command": "node",
      "args": ["${absolute_path_to_project}/build/index.js"],
      "envFile": ".env"
    }
  }
}
  1. Development commands:

# Start the server
npm start

# Run tests
npm test

# Build for production
npm run build

# Publish to npm (maintainers only)
npm publish --access public

Project Structure

twitter-mcp/
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ index.ts           # Main server entry point
โ”‚   โ”œโ”€โ”€ twitter-api.ts     # Twitter API client
โ”‚   โ”œโ”€โ”€ types.ts           # TypeScript type definitions
โ”‚   โ”œโ”€โ”€ formatter.ts       # Response formatting
โ”‚   โ”œโ”€โ”€ types/            # Type declarations
โ”‚   โ”‚   โ””โ”€โ”€ modelcontextprotocol.d.ts
โ”‚   โ””โ”€โ”€ evals/
โ”‚       โ””โ”€โ”€ evals.ts       # Test utilities
โ”œโ”€โ”€ .github/              # GitHub Actions workflows
โ”‚   โ””โ”€โ”€ workflows/
โ”‚       โ””โ”€โ”€ ci.yml        # CI pipeline
โ”œโ”€โ”€ build/               # Compiled JavaScript (generated)
โ”œโ”€โ”€ package.json        # Project metadata and dependencies
โ”œโ”€โ”€ tsconfig.json       # TypeScript configuration
โ”œโ”€โ”€ .gitignore         # Git ignore rules
โ”œโ”€โ”€ .env.example       # Example environment variables
โ”œโ”€โ”€ CHANGELOG.md       # Version history
โ”œโ”€โ”€ CONTRIBUTING.md    # Contribution guidelines
โ””โ”€โ”€ README.md         # Project documentation

Scripts

  • npm run build - Compile TypeScript to JavaScript

  • npm start - Run the compiled server

  • npm run prepublishOnly - Build before publishing

Troubleshooting

Common Issues

1. Authentication Errors

Problem: "401 Unauthorized" or authentication failed

Solutions:

  • Verify Twitter API credentials in Developer Portal

  • Ensure all four tokens are correct and complete

  • Check app permissions (needs Read + Write)

  • Try regenerating access tokens

  • Verify .env file format if using local development

2. Rate Limits

Problem: "Rate limit exceeded" or requests failing

Solutions:

  • Built-in rate limiting protects against overuse

  • Wait 15 minutes for limits to reset

  • Check your Twitter API tier limits

  • Use exponential backoff for retries

  • Monitor usage in Twitter Developer Portal

3. Image Upload Issues

Problem: Image upload fails or missing media

Solutions:

  • Verify file exists and is readable

  • Check size limits: 5MB (images), 15MB (GIFs)

  • Ensure format is supported (JPG, PNG, GIF, WEBP)

  • Use absolute file paths

  • Check file permissions

  • Verify image is not corrupted

3. "Image Upload Failed"

Problem: Image file cannot be uploaded.

Solutions:

  • Verify the file path is correct and absolute

  • Check file exists and is readable

  • Ensure file size is under limits (5MB for images, 15MB for GIFs)

  • Verify file format is supported (JPG, PNG, GIF, WEBP)

  • Check file permissions

4. "Module Not Found" Error

Problem: Dependencies not installed or build not completed.

Solution:

# Remove old dependencies
rm -rf node_modules package-lock.json

# Reinstall
npm install

# Rebuild
npm run build

5. Server Not Responding in Claude

Problem: MCP server not connecting to Claude.

Solutions:

  • Restart Claude Desktop completely

  • Check config file syntax is valid JSON

  • Verify file path in config matches actual location

  • Check Node.js is installed: node --version

  • Look for errors in Claude's logs

Debug Mode

To see detailed logs, check:

Windows:

%APPDATA%\Claude\logs\

macOS:

~/Library/Logs/Claude/

Linux:

~/.config/Claude/logs/

Environment Variables

Posting tools require Twitter OAuth credentials. search_tweets can use Twitter OAuth credentials, the optional Hermes Tweet/Xquik read-only backend, or the optional GetXAPI read-only backend.

Variable

Description

Required

API_KEY

Twitter API Key

For posting and Twitter API search

API_SECRET_KEY

Twitter API Secret Key

For posting and Twitter API search

ACCESS_TOKEN

Twitter Access Token

For posting and Twitter API search

ACCESS_TOKEN_SECRET

Twitter Access Token Secret

For posting and Twitter API search

XQUIK_API_KEY

Optional Hermes Tweet/Xquik key for search_tweets

No

HERMES_TWEET_API_KEY

Optional alias for XQUIK_API_KEY

No

XQUIK_BASE_URL

Optional Xquik base URL, defaults to https://xquik.com

No

GETXAPI_API_KEY

Optional GetXAPI key for search_tweets

No

GETXAPI_BASE_URL

Optional GetXAPI base URL, defaults to https://api.getxapi.com

No

Security Best Practices

  1. Never commit credentials to version control

  2. Use environment variables for sensitive data

  3. Rotate credentials periodically

  4. Monitor API usage in Twitter Developer Portal

  5. Set up alerts for unusual activity

  6. Use separate credentials for development and production

Limitations

  • Maximum tweet length: 280 characters

  • Image file size limits: 5MB (images), 15MB (GIFs)

  • Rate limits apply based on your Twitter API tier

  • Media must be uploaded before tweeting (handled automatically)

Testing

This project uses Jest for testing. Run tests with:

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm test -- --coverage

Writing Tests

Test files are located in src/evals/. Example test:

Contributing

Contributions are welcome! Please follow these steps:

  1. Fork & Clone:

    git clone https://github.com/genaiwithms/twitter-mcp.git
    cd twitter-mcp
  2. Create Branch:

    git checkout -b feature/your-feature
    # or
    git checkout -b fix/your-bugfix
  3. Make Changes:

    • Follow TypeScript practices

    • Add/update tests

    • Update documentation

  4. Test & Build:

    npm install
    npm run build
    npm test
  5. Commit & Push:

    git add .
    git commit -m "feat: add amazing feature"
    git push origin feature/your-feature
  6. Open Pull Request:

    • Use clear title and description

    • Reference issues if applicable

    • Include test results

    • Update documentation

Commit Messages

Follow Conventional Commits:

  • feat: New feature

  • fix: Bug fix

  • docs: Documentation

  • test: Tests

  • refactor: Code refactoring

  • chore: Maintenance

Contributors

Thanks to everyone who contributes to Twitter MCP Server โค๏ธ

Support

Acknowledgments

  • Model Context Protocol ecosystem

  • Claude Desktop community

  • twitter-api-v2 maintainers

  • Xquik team

  • GetXAPI team

  • Open-source contributors

Special thanks to all community contributors who help improve this project.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Available Tools

10 tools
draft_quote_tweetA

Quote retweets an existing tweet with the LLM's commentary. Use this tool when the LLM needs to share an existing tweet with added perspective, endorsement, critique, or reactionโ€”for example, quoting a news article with analysis, sharing a post with a comment, or amplifying content with context. The commentary appears as the new tweet text with the quoted tweet embedded below it. The commentary must be 280 characters or fewer. Returns the created quote tweet ID, text, and a URL to the tweet on X/Twitter.

Inputs: commentary (required), target_tweet_id (required). Returns: data, status, message

engage_with_tweetA

Performs quick engagement actions on a tweet: like (favourite), retweet (repost), or bookmark (save for later). Use this tool when the LLM needs to interact with content on X/Twitterโ€”for example, liking a post to show appreciation, retweeting to share with followers, or bookmarking to save for later reference. The action parameter must be one of "like", "retweet", or "bookmark". Returns a success boolean confirming the action was performed.

Inputs: action (required), tweet_id (required). Returns: data, status, message

fetch_thread_historyA

Retrieves the full conversation thread for a given tweet. Use this tool when the LLM needs to understand the context of a conversation, read previous replies and the original tweet, or analyze the full discussion flow. Input is a tweet_id. The tool first looks up the tweet to find its conversation_id, then searches for all tweets in that conversation and returns them ordered chronologically (oldest first). Each tweet includes author_id, text, timestamps, engagement metrics, and the in_reply_to_tweet_id for mapping reply relationships.

Inputs: tweet_id (required). Returns: data, status, message

get_user_profile_contextA

Fetches a comprehensive Twitter/X user profile including bio, profile metadata, public metrics (followers, following, tweet count), the pinned tweet (if set), and the 5 most recent original tweets. Use this tool when the LLM needs to understand who a user is before engaging with themโ€”for example, checking credibility, reading their bio, reviewing their recent activity, or deciding whether to reply, retweet, or quote. Input is the @username (without the @ symbol). Returns a rich combined JSON object with all profile context in one call.

Inputs: username (required). Returns: data, status, message

media_extraction_helperA

Extracts direct media URLs (images, videos, animated GIFs) from a tweet. Use this tool when the LLM needs to access media content from a tweetโ€”for example, to view an attached image, download a video, analyze media metadata, or pass media URLs to other tools. For photos, returns the direct image URL. For videos and animated GIFs, returns all available variants with direct URLs, bit rates, and content types. The highest bitrate MP4 variant is typically the best quality video. Returns the tweet ID, media array with type/URL/dimensions/duration, and total media count.

Inputs: tweet_id (required). Returns: data, status, message

post_tweetA

Posts a new text-only tweet to the authenticated Twitter/X account. Use this tool when the LLM needs to publish a status update, share information, announce something, or reply to an existing tweet in a thread. The tweet text must be 280 characters or fewer. Optionally accepts a reply_to_tweet_id to post as a threaded reply. Returns the created tweet ID, full text, author identifier, and creation timestamp. Prefer this over post_tweet_with_image when no media attachment is needed.

Inputs: text (required), reply_to_tweet_id. Returns: data, status, message

post_tweet_with_imageA

Posts a new tweet with an attached image file to the authenticated Twitter/X account. Use this tool when the LLM needs to publish a status update that includes a photo, graphic, screenshot, or any visual media. The image is uploaded from a local filesystem path (supports JPEG, PNG, GIF, WebP). The accompanying text must be 280 characters or fewer. Optionally accepts a reply_to_tweet_id for threaded replies. Returns the created tweet object with ID, text, author, and timestamp. Falls back to the standard Twitter API v2 media upload endpoint.

Inputs: text (required), image_path (required), reply_to_tweet_id. Returns: data, status, message

publish_smart_threadA

Splits long AI-generated text into multiple tweets (each โ‰ค280 characters) and posts them as a threaded reply chain. Use this tool when the LLM needs to publish content that exceeds the 280-character single tweet limitโ€”for example, announcements, tutorials, story threads, listicles, or any long-form content. The content is split first by paragraph breaks (double newlines) then by sentence boundaries. Each chunk is posted in sequence as a reply to the previous tweet, forming a connected thread. Returns the full thread with tweet IDs and a URL to the first tweet.

Inputs: content (required). Returns: data, status, message

search_recent_mentionsA

Searches for recent tweets mentioning the authenticated user or matching a custom query. When no query is provided, fetches tweets that mention the authenticated account. When a query is provided, uses the Twitter recent search API to find matching tweets. Use this tool when the LLM needs to monitor mentions of the user, track brand/conversation mentions, or search for recent tweets on a topic. Each result includes the tweet text, author info, timestamp, and engagement metrics. Returns up to max_results tweets (default 10, max 100).

Inputs: query, max_results. Returns: data, status, message

search_tweetsA

Searches Twitter/X for recent tweets matching a query string. Use this tool when the LLM needs to find tweets by keyword, hashtag, mention, or advanced filters (date ranges, language, engagement thresholds). Supports Twitter's full advanced search syntax. Returns a list of matching tweets with their IDs, text, author IDs, and creation timestamps, plus pagination metadata (next_token) for retrieving additional results. Can use alternative backends (XQuik or GetXAPI) when their respective API keys are configured. The count parameter controls how many results (10-100) are returned per call.

Inputs: count (required), query (required). Returns: data, status, message

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A4.3/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: posting, searching, profile fetching, thread retrieval, and engagement. However, post_tweet and post_tweet_with_image are very similar (differing only by media attachment), and search_tweets vs search_recent_mentions could be confused since both search for tweets, though one is user-centric.

    Naming Consistency4/5

    Tool names mostly follow a verb_noun pattern (post_tweet, search_tweets, fetch_thread_history, draft_quote_tweet, engage_with_tweet). Minor deviations include publish_smart_thread (verb_adjective_noun) and media_extraction_helper (noun_verb_noun), which break the pattern slightly but remain readable.

    Tool Count5/5

    10 tools is well-scoped for a Twitter MCP server, covering posting, searching, reading profiles, thread management, and engagement without unnecessary bloat. Each tool serves a distinct functional need.

    Completeness4/5

    The server covers core Twitter workflows: posting (text, image, threads, quote tweets), searching, profile context, thread history, mentions, media extraction, and engagement. Missing operations like deleting tweets, following/unfollowing, or direct messaging are notable but not critical for typical LLM use cases.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables creating, managing, and publishing X/Twitter posts, threads, and replies directly through Claude chat. Supports draft management with the ability to create, list, publish, and delete tweet drafts.
      10
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables searching X (formerly Twitter) using xAI's Responses API with support for filtering by handles, date ranges, and media understanding, returning structured results with citations.
      1
      18 npm
      1
      MIT