# X MCP Server

A Model Context Protocol (MCP) server for posting tweets to X (Twitter) and interacting with the X API.

<a href="https://glama.ai/mcp/servers/@krishna-paulraj/x-mcp-server">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@krishna-paulraj/x-mcp-server/badge" alt="X Server MCP server" />
</a>

## Features

- **Post Tweets**: Create and post tweets to X (Twitter)
- **Get User Timeline**: Retrieve your recent tweets
- **Search Tweets**: Search for tweets using queries
- **Reply to Tweets**: Reply to existing tweets
- **Error Handling**: Comprehensive error handling and validation

## Prerequisites

1. **X Developer Account**: You need a Twitter/X developer account
   - Go to [Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard)
   - Create a new app and get your API credentials

2. **Node.js**: Version 18 or higher

## Setup

1. **Clone and Install Dependencies**:
   ```bash
   npm install
   ```

2. **Configure Environment Variables**:
   ```bash
   cp env.example .env
   ```
   
   Edit `.env` and add your X API credentials:
   ```env
   X_API_KEY=your_api_key_here
   X_API_SECRET=your_api_secret_here
   X_ACCESS_TOKEN=your_access_token_here
   X_ACCESS_TOKEN_SECRET=your_access_token_secret_here
   ```

3. **Build the Project**:
   ```bash
   npm run build
   ```

## Usage

### Running the Server

```bash
# Development mode
npm run dev

# Production mode
npm start
```

### Available Tools

The server provides the following tools:

#### 1. `post_tweet`
Post a new tweet to X.

**Parameters:**
- `text` (required): The tweet content (max 280 characters)
- `reply_to_tweet_id` (optional): ID of the tweet to reply to

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

#### 2. `get_user_timeline`
Get your recent tweets.

**Parameters:**
- `count` (optional): Number of tweets to retrieve (default: 10, max: 100)

**Example:**
```json
{
  "count": 5
}
```

#### 3. `search_tweets`
Search for tweets using a query.

**Parameters:**
- `query` (required): Search query
- `count` (optional): Number of results (default: 10, max: 100)

**Example:**
```json
{
  "query": "MCP protocol",
  "count": 20
}
```

## MCP Client Configuration

To use this server with an MCP client, add it to your client configuration:

```json
{
  "mcpServers": {
    "x-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "X_API_KEY": "your_api_key",
        "X_API_SECRET": "your_api_secret",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}
```

## Development

### Project Structure

```
x-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── env.example           # Environment variables template
└── README.md            # This file
```

### Scripts

- `npm run build`: Compile TypeScript to JavaScript
- `npm start`: Run the compiled server
- `npm run dev`: Run in development mode with hot reload
- `npm test`: Run tests (when implemented)

## Error Handling

The server includes comprehensive error handling for:

- Missing API credentials
- Invalid tweet content (length, format)
- API rate limits
- Network errors
- Invalid parameters

## Security Notes

- Never commit your `.env` file to version control
- Keep your API credentials secure
- Use environment variables for all sensitive data
- Consider using a `.gitignore` file to exclude sensitive files

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
1. Check the error messages for common issues
2. Verify your API credentials are correct
3. Ensure you have the necessary X API permissions
4. Check the X API documentation for rate limits and restrictions