Skip to main content
Glama
GenAIwithMS

Twitter MCP Server

by GenAIwithMS
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

Twitter MCP Server

Connect AI assistants to X (Twitter) using the Model Context Protocol

Post tweets • Upload images • Search tweets • Reply to conversations • Look up user profiles • Fetch conversation threads • Monitor mentions • Publish smart threads • Quote tweets • Extract media • Like, retweet & bookmark

twitter-mcp MCP server

npm version License: MIT Node Version TypeScript

GitHub Stars GitHub Forks

🚀 Quick Start  •  ✨ Features  •  📖 Documentation  •  🤝 Contributing

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
commentaryYesThe text commentary to accompany the quoted tweet. This becomes the text of the new quote tweet, displayed above the quoted content. Maximum 280 characters.
target_tweet_idYesThe unique numeric string ID of the existing tweet to quote. The quoted tweet will appear embedded below the commentary in the new tweet.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYesContainer holding the created quote tweet details.
statusYesIndicates the outcome of the operation: "success" or "error".
messageYesA human-readable summary of the result.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description discloses key behaviors: commentary appears above quoted tweet, character limit (280), and return values (ID, text, URL). It adds context beyond the input schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at 4 sentences, front-loaded with purpose, and well-structured. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 parameters, no nested objects) and the presence of an output schema, the description covers all necessary information: usage, constraints, and return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds meaning by explaining how parameters relate (e.g., quoted tweet embedded below commentary). It reinforces the character limit and purpose of each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: 'Quote retweets an existing tweet with the LLM's commentary.' It distinguishes from siblings like post_tweet by specifying the quoting behavior and provides examples of when to use it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use scenarios (sharing with perspective, endorsement, critique, reaction) and examples. It implicitly distinguishes from post_tweet but does not explicitly state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesThe engagement action to perform: "like" to favourite the tweet, "retweet" to repost it, or "bookmark" to save it to your bookmarks for later.
tweet_idYesThe unique numeric string ID of the tweet to interact with.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYesContainer holding the engagement result.
statusYesIndicates the outcome of the operation: "success" or "error".
messageYesA human-readable summary of the result.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It mentions the return value (success boolean) and constrains the action parameter, but it does not discuss potential side effects, rate limits, authorization requirements, or error scenarios. Adequate but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, with the first sentence defining the tool's actions and the second providing usage context and return info. It is front-loaded and contains no redundant or unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the description covers purpose, usage, parameters, and return value. The presence of an output schema reduces the need to describe return details. However, it lacks guidance on error handling or prerequisites (e.g., user authentication), which slightly reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters with descriptions. The description reiterates the action enum options and implies the tweet_id's role, adding minimal value beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the action set (like, retweet, bookmark) and the target (tweet). It clearly distinguishes from sibling tools like 'post_tweet' or 'draft_quote_tweet' by focusing on engagement actions on existing tweets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool ('when the LLM needs to interact with content on X/Twitter') and concrete examples. It does not explicitly state when not to use it, but the context is sufficient to differentiate from posting or drafting tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
tweet_idYesThe unique numeric string ID of the tweet to retrieve the conversation thread for. The tool will look up the tweet, find its conversation_id, and return all tweets in that conversation thread chronologically.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYesContainer holding the conversation ID and ordered thread array.
statusYesIndicates the outcome of the operation: "success" or "error".
messageYesA human-readable summary of the result.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses the tool's behavior: it looks up the tweet, finds conversation_id, retrieves all tweets in that conversation, and returns them chronologically. It also lists included fields per tweet. No mention of error handling or rate limits, but the core behavior is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with two sentences plus a brief list of included fields. It is front-loaded with the main purpose and structured logically.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple single-parameter schema and presence of an output schema, the description covers the full process and expected output. It is complete for an agent to understand and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (tweet_id) with full schema description. The description adds meaning by explaining how tweet_id is used (to find conversation_id and fetch the thread), going beyond the schema's basic definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the full conversation thread for a tweet, with specific steps (lookup tweet, find conversation_id, fetch all tweets chronologically). It distinguishes from siblings like search_tweets which do not provide thread context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly guides when to use: 'when the LLM needs to understand the context of a conversation, read previous replies, or analyze the full discussion flow.' It does not mention when not to use, but the guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
usernameYesThe Twitter/X username (handle) to look up. Do NOT include the @ symbol. Example: "elonmusk", "twitter". The username is case-insensitive and will be resolved to the canonical Twitter user profile.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYesContainer holding the user profile data, bio, metrics, pinned tweet, and recent tweets.
statusYesIndicates the outcome of the operation: "success" or "error".
messageYesA human-readable summary of the result.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. It details all fetched content and input format. Lacks mention of rate limits or auth requirements, but for a read-only tool this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured and front-loaded with purpose. Slightly wordy but each sentence provides useful info. Could be tighter, but still efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given single parameter and output schema, description fully covers what the tool returns and when to use. Complete for a profile lookup context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage 100% with clear description. Description adds value beyond schema by specifying no @ symbol, case-insensitivity, and examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it fetches a comprehensive user profile including bio, metadata, metrics, pinned tweet, and recent tweets. Distinguishes from siblings (post_tweet, search_tweets) as a read-only profile tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: when LLM needs to understand a user before engaging. Provides examples like checking credibility or deciding to interact. Could mention alternatives but sufficiently clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
tweet_idYesThe unique numeric string ID of the tweet to extract media from. The tool will fetch the tweet with media expansions and return direct URLs for all attached images, videos, and animated GIFs.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYesContainer holding the extracted media URLs and metadata.
statusYesIndicates the outcome of the operation: "success" or "error".
messageYesA human-readable summary of the result.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description details behavior: return format for photos vs videos/GIFs, mentioning bitrates and highest quality, along with returned fields (tweet ID, media array, count). Lacks mention of rate limits or auth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise, front-loaded with main action, and every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given single parameter, presence of output schema, and no nested objects, the description fully covers input, output, and behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with one parameter. Description adds context by explaining the tool fetches tweet with media expansions, supplementing the schema's brief description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool extracts direct media URLs from a tweet, specifying types (images, videos, animated GIFs). It distinguishes from siblings like post_tweet or search_tweets, which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use (e.g., to view attached image, download video) but does not mention when not to use or provide alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesThe main body text of the tweet. Maximum 280 characters. Supports Unicode, emoji, hashtags (#), mentions (@), and URLs. The text will be posted verbatim to Twitter as a new status update.
reply_to_tweet_idNoThe unique numeric ID of an existing tweet to reply to. When provided, the new tweet will be posted as a threaded reply directly beneath the specified parent tweet. Omit this field to post a top-level (non-reply) tweet.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYesContainer holding the created tweet details.
statusYesIndicates the outcome of the operation: "success" or "error".
messageYesA human-readable summary of the result, e.g. "Tweet posted successfully".

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully carries the burden. It discloses the 280-character limit, optional reply parameter, and return fields. However, it does not mention authentication requirements, rate limits, or any potential side effects beyond posting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph of five sentences, starting with the core purpose. Every sentence adds necessary information without redundancy, making it concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (2 params, 1 required, output schema exists), the description covers purpose, usage, parameters, and return values adequately. It lacks error handling or rate limit info, but for a simple post tool, this is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents both parameters well. The description adds value by explaining that it's text-only and clarifying the reply function, but does not significantly augment the schema's meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it posts a text-only tweet to the authenticated account. It distinguishes itself from the sibling tool "post_tweet_with_image" by explicitly stating preference when no media attachment is needed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool (publish status updates, share info, announce, reply) and explicitly names an alternative (post_tweet_with_image) for when media is needed. Provides clear context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesThe main body text of the tweet. Maximum 280 characters. This text accompanies the uploaded image in the tweet post.
image_pathYesAbsolute or relative filesystem path to the image file to upload and attach to the tweet. Supported formats: JPEG, PNG, GIF, WebP. The file must exist and be readable at the time of invocation.
reply_to_tweet_idNoThe unique numeric ID of an existing tweet to reply to. When provided, the new tweet-with-image will be posted as a threaded reply. Omit for a standalone tweet.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYesContainer holding the created tweet details.
statusYesIndicates the outcome of the operation: "success" or "error".
messageYesA human-readable summary of the result, e.g. "Tweet posted successfully".

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It details the required file existence, supported formats, character limit, optional reply threading, return object fields, and even mentions the underlying API fallback. Doesn't explicitly state authentication or rate limits, but overall transparent about operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each earning its place: purpose/usage, file constraints, character limit + threading option, return value and backend note. Front-loaded with the main action. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the moderate complexity (3 params, no nested objects, output schema present), the description covers purpose, usage, parameters, and return. Missing details on error handling or rate limits, but sufficient for an agent to invoke correctly. Output schema supplements return info.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (all 3 parameters described in schema). The description adds value by explaining image_path as a filesystem path with supported formats and existence requirement, and clarifies that reply_to_tweet_id is a numeric ID for threading. This goes beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it posts a new tweet with an attached image, distinguishing itself from siblings like post_tweet (text-only) and search_tweets (search). The verb 'Posts' and resource 'new tweet with an attached image file' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('when the LLM needs to publish a status update that includes a photo...') and implies when not by mentioning alternatives (post_tweet for text-only). Also explains optional reply_to_tweet_id for threaded context. Lacks explicit rate limits or prerequisites, but provides clear context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesThe full text content to publish as a thread. Can be thousands of characters long. The tool automatically splits the content into individual tweets (each ≤280 characters) by paragraph breaks (double newlines) and posts them as a threaded reply chain. Use double newlines to indicate where you want tweet breaks to occur. Supports Unicode, emoji, hashtags, mentions, and URLs.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYesContainer holding the posted thread details.
statusYesIndicates the outcome of the operation: "success" or "error".
messageYesA human-readable summary of the result.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes splitting algorithm (paragraph breaks then sentence boundaries), posting sequence (reply chain), and return (thread with IDs and URL). No annotations to contradict. Full behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with main action, then conditions and examples. Every sentence adds value. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all necessary aspects: when to use, how it works, return value. Output schema exists but description also mentions thread with IDs and URL. No missing information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% with parameter description, but the tool description adds significant context: how splitting works, 280-char limit, double newline usage. Provides meaningful extra guidance beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it splits long text into tweets and posts as a threaded reply chain. Distinguishes from siblings like post_tweet (single tweet) and draft_quote_tweet (drafting).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use: when content exceeds 280-character limit (e.g., announcements, tutorials). Does not explicitly say when not to use, but context implies short content should use post_tweet. Could be improved with explicit exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoOptional search query string. When provided, uses the Twitter recent search endpoint to find tweets matching the query. Supports the full Twitter advanced search syntax. When omitted, fetches tweets that mention the authenticated user's account.
max_resultsNoMaximum number of mention/search results to return. Must be between 5 and 100. Defaults to 10.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYesContainer holding the matched tweets and metadata.
statusYesIndicates the outcome of the operation: "success" or "error".
messageYesA human-readable summary of the result.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description discloses behavioral traits: two modes of operation, output contents (tweet text, author, timestamp, metrics), and pagination limits. It lacks explicit mention of rate limits or authentication requirements but covers the core behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise yet complete, organized logically: purpose, mode explanation, use cases, output details, and limits. No extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With only two parameters, full schema coverage, and an output schema, the description covers all necessary aspects: function, usage, output description, and constraints. Nothing is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the description adds context beyond schema by explaining how the query parameter affects behavior and the meaning of max_results, including default and range.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it searches for recent tweets mentioning the authenticated user or matching a custom query, clearly distinguishing two behavioral modes. It differentiates from siblings like search_tweets by specifying scope and use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear use cases such as monitoring mentions and tracking brand mentions, but does not explicitly state when not to use or recommend alternatives among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
countYesNumber of search results to return per request. Must be between 10 and 100 (inclusive). Higher values return more tweets per invocation but increase response latency and API quota consumption.
queryYesThe Twitter search query string. Supports the full Twitter advanced search syntax, including keywords (separated by spaces), exact phrases (in double quotes), from:username, to:username, #hashtag, @mention, lang:XX (ISO language code), until:YYYY-MM-DD, since:YYYY-MM-DD, min_retweets:N, min_faves:N, and filter:media / filter:links / filter:images. The query is URL-encoded and sent directly to the Twitter search API.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYesContainer holding the array of matched tweets and search metadata.
statusYesIndicates the outcome of the operation: "success" or "error".
messageYesA human-readable summary of the search result, e.g. "Search completed successfully".

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It thoroughly discloses behavior: returns list with fields, pagination metadata, alternative backends, and count parameter effects (latency, quota). No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph that front-loads the main purpose and uses efficient language. Some slight redundancy (e.g., 'Searches' and 'Returns'), but overall each sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (2 params, no nested objects) and presence of output schema, the description covers purpose, usage, syntax, return fields, pagination, and backend options comprehensively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds significant extra context: query parameter includes detailed advanced syntax examples, count parameter explains range and performance trade-offs. This goes well beyond schema basics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches for tweets matching a query, using specific verbs and resources. It distinguishes from sibling tools (post_tweet, post_tweet_with_image) by focusing on search/retrieval rather than posting.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool (when needing to find tweets by keyword, hashtag, etc.) and mentions alternative backends. However, it does not provide explicit negative examples or compare to non-sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.3.10
    • Addedengage_with_tweet
    • Addedmedia_extraction_helper
  2. 4 tool updatesv0.3.9
    • Addeddraft_quote_tweet
    • Addedfetch_thread_history
    • Addedpublish_smart_thread
    • Addedsearch_recent_mentions
  3. 1 tool updatev0.3.8
    • Addedget_user_profile_context
  4. 3 tool updatesv0.1.0
    • First observedpost_tweet
    • First observedpost_tweet_with_image
    • First observedsearch_tweets
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a distinct purpose: text-only posting, image posting, and searching. No overlap in functionality, making it easy for an agent to select the correct tool.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern ('post_tweet', 'post_tweet_with_image', 'search_tweets'), making them predictable and easy to understand.

Tool Count4/5

With only 3 tools, the set is minimal but covers core actions for a Twitter server. The count is slightly low but reasonable for a focused implementation.

Completeness2/5

The set lacks essential operations like deleting tweets, retrieving a single tweet, or accessing timelines, which limits the agent's ability to perform common Twitter workflows.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • X(Twitter) MCP Server

    cjkcr
    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

  • X Search MCP

    konarkm
    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
    31
    1
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/GenAIwithMS/twitter-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server