A Model Context Protocol (MCP) server that provides access to Twitter data through the TwitterAPI.io service. This server enables Claude and other MCP clients to interact with Twitter's ecosystem without requiring Twitter developer account approval.

Attribution: This project is a fork of kinhunt/twitterapi-mcp with bug fixes and improvements to match the official TwitterAPI.io documentation.

Features

User Information: Get detailed user profiles, followers, and following lists
Tweet Operations: Search tweets, get tweet details, replies, and user timelines
Search Capabilities: Advanced search for both tweets and users
Write Actions: Post tweets and interact with content (requires login)
Pagination Support: All list endpoints support cursor-based pagination
Enterprise Ready: Proxy support and robust error handling
No Twitter Auth: Uses TwitterAPI.io which doesn't require Twitter developer approval

Installation

Quick Start with npx (Recommended)

npx twitterapi-mcp-server

Global Installation

npm install -g twitterapi-mcp-server

Local Installation

npm install twitterapi-mcp-server

Configuration

Getting an API Key

Visit TwitterAPI.io
Create an account and log in
Get your API key from the dashboard
The API key format looks like: new1_xxxxxxxxxxxxxxxxxxxxx

Environment Variables

Variable	Required	Description
`TWITTERAPI_API_KEY`	Yes	Your TwitterAPI.io API key
`PROXY_URL`	No	Proxy URL for enterprise environments
`HTTP_PROXY`	No	Alternative proxy configuration
`HTTPS_PROXY`	No	Alternative proxy configuration

MCP Client Configuration

Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "twitterapi": {
      "command": "npx",
      "args": ["-y", "twitterapi-mcp-server"],
      "env": {
        "TWITTERAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop with Proxy

{
  "mcpServers": {
    "twitterapi": {
      "command": "npx",
      "args": ["-y", "twitterapi-mcp-server"],
      "env": {
        "TWITTERAPI_API_KEY": "your_api_key_here",
        "PROXY_URL": "http://proxy.company.com:8080"
      }
    }
  }
}

Cursor IDE

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "twitterapi": {
      "command": "npx",
      "args": ["-y", "twitterapi-mcp-server"],
      "env": {
        "TWITTERAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "twitterapi": {
      "command": "npx",
      "args": ["-y", "twitterapi-mcp-server"],
      "env": {
        "TWITTERAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Using with Node directly

If you prefer to run with Node directly instead of npx:

{
  "mcpServers": {
    "twitterapi": {
      "command": "node",
      "args": ["/path/to/twitterapi-mcp-server/build/index.js"],
      "env": {
        "TWITTERAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

User Information

Tool	Description	Required Params	Optional Params
`get_user_by_username`	Get user details by username	`username`	-
`get_user_by_id`	Get user details by user ID	`user_id`	-
`get_user_followers`	Get user's followers (200/page)	`username`	`cursor`, `pageSize`
`get_user_following`	Get users someone follows (200/page)	`username`	`cursor`, `pageSize`
`search_users`	Search for users by keyword	`query`	`cursor`

Tweet Operations

Tool	Description	Required Params	Optional Params
`get_user_tweets`	Get tweets from a user (20/page)	`username` or `userId`	`cursor`, `includeReplies`
`search_tweets`	Search tweets by keywords	`query`	`queryType` (Latest/Top), `cursor`
`get_tweet_by_id`	Get tweets by IDs	`tweet_ids` (array)	-
`get_tweet_replies`	Get replies to a tweet (20/page)	`tweetId`	`cursor`, `sinceTime`, `untilTime`

Tool	Description	Required Params	Optional Params
`login_user`	Login to Twitter account	`user_name`, `email`, `password`, `proxy`	`totp_secret`
`create_tweet`	Post new tweets	`tweet_text`, `proxy`	`reply_to_tweet_id`, `attachment_url`, `media_ids`

Examples

Get User Information

// Get user by username
await get_user_by_username({ username: "elonmusk" })

// Get user followers with pagination
await get_user_followers({
  username: "elonmusk",
  pageSize: 100
})

// Get next page using cursor
await get_user_followers({
  username: "elonmusk",
  cursor: "next_cursor_from_previous_response"
})

Search and Retrieve Tweets

// Search latest tweets
await search_tweets({
  query: "artificial intelligence",
  queryType: "Latest"
})

// Search top/popular tweets
await search_tweets({
  query: "OpenAI",
  queryType: "Top"
})

// Advanced search with operators
await search_tweets({
  query: "AI from:elonmusk since:2024-01-01"
})

// Get user's recent tweets
await get_user_tweets({ username: "openai" })

// Get user's tweets including replies
await get_user_tweets({
  username: "openai",
  includeReplies: true
})

// Get specific tweets by IDs
await get_tweet_by_id({
  tweet_ids: ["1234567890123456789", "9876543210987654321"]
})

// Get replies to a tweet
await get_tweet_replies({
  tweetId: "1234567890123456789"
})

// Login first (requires residential proxy)
await login_user({
  user_name: "your_username",
  email: "your_email@example.com",
  password: "your_password",
  proxy: "http://user:pass@proxy:port"
})

// Post a tweet
await create_tweet({
  tweet_text: "Hello from MCP!",
  proxy: "http://user:pass@proxy:port"
})

// Reply to a tweet
await create_tweet({
  tweet_text: "Great point!",
  reply_to_tweet_id: "1234567890123456789",
  proxy: "http://user:pass@proxy:port"
})

Pagination

All list endpoints return paginated results with cursor-based navigation:

{
  "data": [...],
  "has_next_page": true,
  "next_cursor": "cursor_string_for_next_page"
}

To get the next page, pass the next_cursor value as the cursor parameter in your next request.

API Pricing

TwitterAPI.io offers pay-as-you-go pricing:

Operation	Price
Tweets	$0.15 per 1,000
User profiles	$0.18 per 1,000
Followers/Following	$0.15 per 1,000
Login	$0.003 per call
Create tweet	$0.003 per call

Minimum charge: $0.00015 per request
No monthly fees
Free trial credits available
Discounted rates for students and research institutions

Development

Building from Source

git clone https://github.com/Jing-yilin/twitterapi-mcp-server.git
cd twitterapi-mcp-server
npm install
npm run build

Running Tests

# Using bun
bun test

# Or with npm (requires bun installed)
npm test

Testing the Server Manually

# Set your API key
export TWITTERAPI_API_KEY="your_api_key"

# Test tools list
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node build/index.js

# Test a tool call
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_user_by_username", "arguments": {"username": "elonmusk"}}}' | node build/index.js

Project Structure

twitterapi-mcp-server/
├── src/
│   ├── index.ts           # Main server implementation
│   ├── index.test.ts      # Unit tests
│   └── integration.test.ts # Integration tests
├── build/                  # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Error Handling

The server handles common errors:

Error	Cause	Solution
401 Unauthorized	Invalid API key	Check your `TWITTERAPI_API_KEY`
402 Payment Required	Insufficient credits	Add credits at TwitterAPI.io dashboard
429 Rate Limited	Too many requests	Wait and retry, or reduce request rate
400 Bad Request	Invalid parameters	Check parameter names and formats

Security Considerations

Store API keys as environment variables, never in code
Login credentials are used only for authentication, not stored persistently
All API requests use HTTPS
Proxy support available for enterprise security requirements
The login_cookie from login is stored in memory only for the session

Troubleshooting

"Unauthorized" error

Verify your API key is correct
Check that TWITTERAPI_API_KEY environment variable is set

"Credits not enough" error

Add credits to your TwitterAPI.io account
Check your usage at the dashboard

Server not starting

Ensure Node.js >= 18.0.0 is installed
Run npm run build to compile TypeScript
Check for error messages in stderr

Proxy issues

Verify proxy URL format: http://user:pass@host:port
Test proxy connectivity independently
For HTTPS proxies, use HTTPS_PROXY variable

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

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

Support

API Documentation: docs.twitterapi.io
Issues: GitHub Issues
TwitterAPI.io Support: twitterapi.io

Acknowledgments

Originally forked from kinhunt/twitterapi-mcp
Built on TwitterAPI.io service
Uses the Model Context Protocol
Part of the growing MCP ecosystem

Note: This is an unofficial MCP server for TwitterAPI.io. Make sure to comply with Twitter's Terms of Service when using this tool.

Keywords

FAQs

What is @yilin-jing/twitterapi-mcp?

Is @yilin-jing/twitterapi-mcp well maintained?

Package last updated on 04 Dec 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@yilin-jing/twitterapi-mcp

TwitterAPI MCP Server