# TwitterAPI MCP Server
A Model Context Protocol (MCP) server that provides access to Twitter data through the [TwitterAPI.io](https://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](https://github.com/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)
```bash
npx twitterapi-mcp-server
```
### Global Installation
```bash
npm install -g twitterapi-mcp-server
```
### Local Installation
```bash
npm install twitterapi-mcp-server
```
## Configuration
### Getting an API Key
1. Visit [TwitterAPI.io](https://twitterapi.io/)
2. Create an account and log in
3. Get your API key from the dashboard
4. 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`
```json
{
"mcpServers": {
"twitterapi": {
"command": "npx",
"args": ["-y", "twitterapi-mcp-server"],
"env": {
"TWITTERAPI_API_KEY": "your_api_key_here"
}
}
}
}
```
### Claude Desktop with Proxy
```json
{
"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`):
```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`):
```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:
```json
{
"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` |
### Write Actions (Requires Login)
| 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
```typescript
// 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
```typescript
// 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"
})
```
### Create Content (Requires Login)
```typescript
// 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:
```json
{
"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
```bash
git clone https://github.com/Jing-yilin/twitterapi-mcp-server.git
cd twitterapi-mcp-server
npm install
npm run build
```
### Running Tests
```bash
# Using bun
bun test
# Or with npm (requires bun installed)
npm test
```
### Testing the Server Manually
```bash
# 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
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- **API Documentation**: [docs.twitterapi.io](https://docs.twitterapi.io/)
- **Issues**: [GitHub Issues](https://github.com/Jing-yilin/twitterapi-mcp-server/issues)
- **TwitterAPI.io Support**: [twitterapi.io](https://twitterapi.io/)
## Acknowledgments
- Originally forked from [kinhunt/twitterapi-mcp](https://github.com/kinhunt/twitterapi-mcp)
- Built on [TwitterAPI.io](https://twitterapi.io/) service
- Uses the [Model Context Protocol](https://modelcontextprotocol.io/)
- 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.
