# MCP Twitter/X Server

A Model Context Protocol (MCP) server that provides integration with Twitter/X, allowing you to read posts from users and create new posts.

## Features

- **Read Posts**: Fetch the latest tweets from any public Twitter/X user
- **Create Posts**: Post new tweets to your Twitter/X account
- **Get Specific Post**: Retrieve a specific tweet by its ID
- **Search Posts**: Search for tweets matching a query
- **Configurable Options**: Control tweet count, include/exclude replies and retweets

## Available Tools

### 1. `read_posts`
Fetch the latest posts from a specified Twitter/X user.

**Parameters:**
- `username` (required): The Twitter/X username (without @)
- `count` (optional): Number of tweets to fetch (1-100, default: 20)
- `includeReplies` (optional): Whether to include replies (default: false)
- `includeRetweets` (optional): Whether to include retweets (default: true)

**Example:**
```json
{
  "username": "elonmusk",
  "count": 10,
  "includeReplies": false,
  "includeRetweets": true
}
```

### 2. `create_post`
Create a new post on Twitter/X.

**Parameters:**
- `text` (required): The text content of the tweet (max 280 characters)

**Example:**
```json
{
  "text": "Hello, world! This is my first tweet via MCP."
}
```

### 3. `get_post`
Get a specific tweet by ID.

**Parameters:**
- `tweetId` (required): The ID of the tweet to retrieve

**Example:**
```json
{
  "tweetId": "1234567890123456789"
}
```

### 4. `search_posts`
Search for tweets matching a query.

**Parameters:**
- `query` (required): The search query
- `count` (optional): Number of tweets to fetch (1-100, default: 10)
- `resultType` (optional): "recent" or "popular" (default: "recent")

**Example:**
```json
{
  "query": "AI and machine learning",
  "count": 15,
  "resultType": "popular"
}
```

## Setup

### 1. Prerequisites

- Node.js 18 or higher
- Twitter Developer Account with API access

### 2. Twitter API Setup

1. Go to the [Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard)
2. Create a new app or use an existing one
3. Generate the following credentials:
   - API Key
   - API Secret
   - Access Token
   - Access Token Secret
   - Bearer Token

4. Make sure your app has the following permissions:
   - Read and Write (for creating posts)
   - Users and Tweets (for reading posts)

### 3. Installation

#### Option A: Local Installation

1. Clone or download this repository
2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the project:
   ```bash
   npm run build
   ```

4. Set up environment variables:
   ```bash
   cp .env.example .env
   ```

#### Option B: Docker Installation

1. Clone or download this repository
2. Set up environment variables:
   ```bash
   cp .env.example .env
   ```

3. Build and run with Docker:
   ```bash
   docker build -t mcp-twitter-x-server .
   docker run -it --env-file .env mcp-twitter-x-server
   ```

   Or use Docker Compose:
   ```bash
   docker-compose up --build
   ```

5. Edit `.env` and add your Twitter API credentials:
   ```env
   TWITTER_API_KEY=your_api_key_here
   TWITTER_API_SECRET=your_api_secret_here
   TWITTER_ACCESS_TOKEN=your_access_token_here
   TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret_here
   TWITTER_BEARER_TOKEN=your_bearer_token_here
   ```

### 4. Configuration for MCP Clients

Add the server to your MCP client configuration. For example, in Claude Desktop:

```json
{
  "mcpServers": {
    "mcp-twitter-x-server": {
      "command": "node",
      "args": ["/path/to/MCP-X/dist/index.js"],
      "env": {
        "TWITTER_API_KEY": "your_api_key_here",
        "TWITTER_API_SECRET": "your_api_secret_here",
        "TWITTER_ACCESS_TOKEN": "your_access_token_here",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret_here",
        "TWITTER_BEARER_TOKEN": "your_bearer_token_here"
      }
    }
  }
}
```

## Usage Examples

### Reading Posts

```bash
# Get latest 5 tweets from @elonmusk (excluding replies)
{
  "tool": "read_posts",
  "arguments": {
    "username": "elonmusk",
    "count": 5,
    "includeReplies": false
  }
}
```

### Creating a Post

```bash
# Post a new tweet
{
  "tool": "create_post", 
  "arguments": {
    "text": "Just set up my MCP Twitter server! 🚀 #MCP #TwitterAPI"
  }
}
```

### Searching Posts

```bash
# Search for recent tweets about AI
{
  "tool": "search_posts",
  "arguments": {
    "query": "artificial intelligence",
    "count": 10,
    "resultType": "recent"
  }
}
```

## Response Format

### Tweet Object Structure

```json
{
  "id": "1234567890123456789",
  "text": "This is a tweet",
  "author": {
    "username": "example_user",
    "name": "Example User",
    "id": "987654321"
  },
  "created_at": "2023-10-01T12:00:00.000Z",
  "metrics": {
    "likes": 42,
    "retweets": 7,
    "replies": 3,
    "quotes": 1
  },
  "url": "https://twitter.com/example_user/status/1234567890123456789"
}
```

## Development

### Scripts

- `npm run build` - Build the TypeScript project
- `npm run start` - Start the server
- `npm run dev` - Development mode with auto-restart
- `npm run clean` - Clean build artifacts

### Project Structure

```
src/
├── index.ts              # Main MCP server
├── twitter-client.ts     # Twitter API v2 wrapper
├── twitter-client-v1.ts  # Twitter API v1.1 fallback
dist/                     # Compiled JavaScript
mcp-config.json           # Sample MCP configuration
.env.example              # Environment variables template
```

## Error Handling

The server includes comprehensive error handling for:

- Invalid Twitter API credentials
- Rate limiting
- User not found
- Tweet not found
- Invalid parameters
- Network errors

All errors are returned in a structured format:

```json
{
  "success": false,
  "error": "Detailed error message"
}
```

## Rate Limiting

The Twitter API has rate limits. The server will throw errors when limits are exceeded. Consider implementing caching or request throttling for production use.

## Security Notes

- Never commit your `.env` file with real credentials
- Use environment variables for all sensitive configuration
- Consider implementing additional authentication for production deployments
- Monitor your Twitter API usage to avoid unexpected charges

## License

MIT License - see LICENSE file for details.

## Docker MCP Registry

This server is designed to be compatible with the [Docker MCP Registry](https://hub.docker.com/mcp). The repository includes:

- `Dockerfile` - Container configuration for production deployment
- `docker-compose.yml` - Easy local testing with Docker
- `tools.json` - Tool definitions for the Docker MCP Registry
- `.dockerignore` - Optimized Docker build context

### Using with Docker MCP Toolkit

This server can be easily installed and managed through Docker Desktop's MCP Toolkit once it's available in the Docker MCP Registry.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with Docker: `docker-compose up --build`
5. Submit a pull request

## Support

For issues related to:
- Twitter API: Check the [Twitter API documentation](https://developer.twitter.com/en/docs)
- MCP Protocol: Check the [MCP documentation](https://modelcontextprotocol.io/)
- This server: Open an issue in this repository