npm package: @siya11rst/twitter-mcp
Description: Twitter MCP Server for AI Agents — Post, Schedule, Analyze, Generate
Author: Raman Thakur
Latest version: 1.0.3

# Twitter MCP

A Model Context Protocol (MCP) server that enables AI systems to interact with Twitter/X, allowing for posting tweets, searching content, and managing Twitter operations.

## 🚀 What is Twitter MCP?

The Model Context Protocol (MCP) is an open standard originally developed by Anthropic designed to enable AI systems to interact securely and effectively with various existing business tools and datasets. This Twitter MCP server acts as a bridge between AI models (like Claude) and Twitter's API, enabling seamless social media interactions.

## ✨ Features

- **Tweet Posting**: Create and publish tweets directly through AI conversations
- **Tweet Search**: Search for tweets using keywords, hashtags, or user mentions
- **User Profile Retrieval**: Get detailed information about Twitter users
- **Timeline Access**: Retrieve user timelines and tweet threads
- **Trend Analysis**: Access trending topics and hashtags
- **Real-time Integration**: Direct integration with Claude Desktop and other MCP-compatible clients

## 📋 Prerequisites

Before setting up Twitter MCP, you'll need:

1. **Twitter Developer Account**: Sign up at [Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard)
2. **API Keys**: Obtain your API credentials from the developer dashboard
3. **Claude Desktop** (or another MCP-compatible client)
4. **Node.js** (if running from source)

## 🔑 Twitter API Setup

1. **Create a Twitter Developer Account**
   - Visit [Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard)
   - Apply for a developer account
   - Create a new project/app

2. **Generate API Keys**
   - Navigate to your app settings
   - Generate the following credentials:
     - API Key
     - API Secret Key  
     - Access Token
     - Access Token Secret

3. **Set Permissions**
   - Ensure your app has read and write permissions for posting tweets
   - Configure OAuth 1.0a settings if required

## ⚙️ Installation & Setup

### Quick Setup (NPM Package)

Add this configuration to your Claude Desktop config file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "twitter-mcp"],
      "env": {
        "API_KEY": "your_api_key_here",
        "API_SECRET_KEY": "your_api_secret_key_here",
        "ACCESS_TOKEN": "your_access_token_here",
        "ACCESS_TOKEN_SECRET": "your_access_token_secret_here"
      }
    }
  }
}
```

### Development Setup

If you want to contribute or run from source:

```bash
# Clone the repository
git clone https://github.com/R1M1N/twitter-mcp.git
cd twitter-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start
```

### Environment Variables

Create a `.env` file in the root directory:

```env
API_KEY=your_twitter_api_key
API_SECRET_KEY=your_twitter_api_secret
ACCESS_TOKEN=your_twitter_access_token
ACCESS_TOKEN_SECRET=your_twitter_access_token_secret
```

## 🔧 Configuration

After setup, restart Claude Desktop. The Twitter MCP server will be available with the following tools:

| Tool | Description | Parameters |
|------|-------------|------------|
| `post_tweet` | Post a new tweet | `text` (string): Tweet content |
| `search_tweets` | Search for tweets | `query` (string): Search query |
| `get_user_profile` | Get user information | `username` (string): Twitter username |
| `get_user_timeline` | Get user's recent tweets | `username` (string): Twitter username |
| `get_trending_topics` | Get trending hashtags | `location` (optional): Location ID |

## 🎯 Usage Examples

Once configured, you can interact with Twitter through Claude:

### Posting Tweets
```
"Can you post a tweet saying 'Hello from Claude! 🤖 #AI #TwitterMCP'"
```

### Searching Content
```
"Search for recent tweets about artificial intelligence"
"Find tweets mentioning @OpenAI from the last week"
"Search for tweets with hashtag #MachineLearning"
```

### User Information
```
"Get information about the user @elonmusk"
"Show me the recent tweets from @OpenAI"
```

### Trend Analysis
```
"What are the current trending topics on Twitter?"
"Show me trending hashtags in the United States"
```

## 🔍 Logs & Debugging

Logs can be found at:
- **Windows**: `%APPDATA%\Claude\logs\mcp-server-twitter.log`
- **macOS**: `~/Library/Logs/Claude/mcp-server-twitter.log`

For debugging:
```bash
# Run with verbose logging
DEBUG=twitter-mcp npm start

# Test specific functionality
npm run test
```

## 🛠️ Development

### Project Structure
```
twitter-mcp/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── twitter-client.ts # Twitter API wrapper
│   ├── tools/            # MCP tool definitions
│   └── types/            # TypeScript type definitions
├── tests/
│   └── evals.ts          # Evaluation tests
├── package.json
├── tsconfig.json
└── README.md
```

### Available Scripts
```bash
npm run build    # Build the TypeScript project
npm run dev      # Run in development mode
npm run test     # Run evaluation tests
npm run lint     # Run ESLint
npm start        # Start the MCP server
```

### Testing with MCP Eval
```bash
# Run evaluation tests
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts
```

## 🔐 Security & Privacy

- **API Key Security**: Never commit API keys to version control
- **Environment Variables**: Use `.env` files for local development
- **Rate Limiting**: Respects Twitter API rate limits
- **Data Privacy**: No data is stored locally; all interactions go through Twitter's API
- **OAuth Support**: Supports OAuth 1.0a authentication flow

## 🚨 Rate Limits & Best Practices

Twitter API has rate limits that you should be aware of:

| Endpoint | Rate Limit | Window |
|----------|------------|--------|
| Post Tweet | 300 requests | 15 minutes |
| Search Tweets | 300 requests | 15 minutes |
| User Lookup | 300 requests | 15 minutes |

**Best Practices:**
- Cache responses when possible
- Implement exponential backoff for rate limit handling
- Use batch requests for multiple operations
- Monitor your API usage through Twitter Developer Portal

## 🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

### Development Guidelines
- Follow TypeScript best practices
- Add JSDoc comments for public methods
- Include tests for new features
- Update documentation as needed

## 🐛 Troubleshooting

### Common Issues

**1. Authentication Errors**
```
Error: Unauthorized (401)
```
- Verify your API keys are correct
- Check that your Twitter app has proper permissions
- Ensure tokens haven't expired

**2. Rate Limit Exceeded**
```
Error: Rate limit exceeded (429)
```
- Wait for the rate limit window to reset
- Implement request throttling
- Consider upgrading your Twitter API plan

**3. MCP Server Not Starting**
```
Error: Cannot connect to MCP server
```
- Check Claude Desktop configuration
- Verify environment variables are set
- Review logs for detailed error messages

## 📚 Related Resources

- **MCP Specification**: [Model Context Protocol](https://spec.modelcontextprotocol.io/)
- **Twitter API Documentation**: [Twitter API v2](https://developer.twitter.com/en/docs/twitter-api)
- **Claude Desktop**: [Claude Desktop Documentation](https://docs.claude.com)
- **MCP Community**: [Claude MCP Community](https://www.claudemcp.com/)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Anthropic](https://www.anthropic.com/) for developing the Model Context Protocol
- Twitter/X for providing the API
- The MCP community for tools and examples
- Contributors and maintainers

## 📞 Support

- **Issues**: Open an issue on GitHub
- **Discussions**: Use GitHub Discussions for questions
- **Documentation**: Check the [MCP documentation](https://spec.modelcontextprotocol.io/)

---

**Made with ❤️ for the AI community**

*Bridging social media and artificial intelligence through seamless integration*