# <img src="https://www.x.com/favicon.ico" alt="X Logo" width="32" height="32"> X (Twitter) MCP Server

This MCP server allows Clients to interact with X (formerly Twitter), enabling comprehensive platform operations including posting tweets, searching content, managing accounts, and organizing lists.

## Quick Start

1. Create an X Developer account and get your API keys from [X Developer Portal](https://developer.twitter.com/en/portal/dashboard)
2. Clone this repository: `git clone https://github.com/Dishant27/twitter-mcp.git`
3. Install dependencies and build: `npm install && npm run build`
4. Set your API keys, either as environment variables or in a `.env` file (copy `.env.example` to `.env` and fill in your values; `.env` is git-ignored, so never commit it)
5. Run the server:
- With environment variables:
```bash
TWITTER_API_KEY=your_api_key \
TWITTER_API_SECRET=your_api_secret \
TWITTER_ACCESS_TOKEN=your_access_token \
TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret \
npm start
```
- Using a `.env` file:
```bash
cp .env.example .env
# edit .env with your own keys, then:
npm start
```

6. Use with a MCP client, such as Claude.

## Claude Configuration

To use this server with Claude, you'll need to set up the MCP configuration. Here's an example of how the configuration structure should look:

```json
{
  "name": "x",
  "display_name": "X",
  "description": "X MCP allows Claude to interact with X (formerly Twitter)",
  "path": "path/to/twitter-mcp/dist/index.js",
  "startup": {
    "env": {
      "TWITTER_API_KEY": "your_api_key",
      "TWITTER_API_SECRET": "your_api_secret",
      "TWITTER_ACCESS_TOKEN": "your_access_token",
      "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret"
    }
  },
  "transport": "stdio"
}
```

Save this configuration in your Claude MCP config directory, typically located at:
- Windows: `%APPDATA%\AnthropicClaude\mcp-servers`
- macOS: `~/Library/Application Support/AnthropicClaude/mcp-servers`
- Linux: `~/.config/AnthropicClaude/mcp-servers`

## Features

### Post Operations
- Post content (up to 280 characters)
- Search for posts by query with customizable result count

### Account Management
- Get profile information for any user or the authenticated account
- Update profile details (name, bio, location, website URL)
- Follow and unfollow users
- List followers for any user or the authenticated account
- List accounts that a user is following

### List Management
- Create new lists (public or private)
- Get information about specific lists
- Retrieve all lists owned by the authenticated user

## Available MCP Tools

| Tool Name | Description |
|-----------|-------------|
| `post_tweet` | Post new content to X |
| `search_tweets` | Search for content on X |
| `get_profile` | Get profile information for a user or the authenticated account |
| `update_profile` | Update the authenticated user's profile |
| `follow_user` | Follow a user |
| `unfollow_user` | Unfollow a user |
| `list_followers` | List followers of a user or the authenticated account |
| `list_following` | List accounts that a user or the authenticated account is following |
| `create_list` | Create a new list |
| `get_list_info` | Get information about a list |
| `get_user_lists` | Get all lists owned by the authenticated user |

## Requirements

- Node.js 18.x or higher
- X Developer account with API keys
- API v1 and v2 access

Built on `@modelcontextprotocol/sdk` 1.x (the `McpServer` / `registerTool` API with zod input schemas). It runs over stdio, so stdout is reserved for the MCP protocol and all logs go to stderr.

## Environment Variables

| Variable | Description |
|----------|-------------|
| `TWITTER_API_KEY` | Your API key |
| `TWITTER_API_SECRET` | Your API secret |
| `TWITTER_ACCESS_TOKEN` | Your access token |
| `TWITTER_ACCESS_TOKEN_SECRET` | Your access token secret |

All four are required; the server exits at startup if any is missing. See `.env.example`.

## Development

```bash
npm run build   # compile TypeScript to dist/
npm run smoke   # start the built server with placeholder keys and check it lists its 11 tools (no X API calls)
```

CI (`.github/workflows/ci.yml`) runs `npm ci`, a type check, the build and the smoke test on pushes and pull requests to `master`.

## Repository Structure

```
twitter-mcp/
├── .github/
│   └── workflows/
│       └── ci.yml      # Build + smoke test
├── code/
│   ├── account_management.py  # Sample Python code for account management
│   ├── post_tweet.py          # Sample Python code for posting content
│   └── retrieve_tweets.py     # Sample Python code for retrieving content
├── src/
│   ├── index.ts        # Main entry point (MCP server and tools)
│   ├── twitter-api.ts  # X API client
│   ├── formatter.ts    # Response formatter
│   └── types.ts        # Type definitions
├── test/
│   └── smoke.mjs       # Stdio smoke test
├── .env.example
├── .gitignore
├── LICENSE
├── package.json
├── package-lock.json
├── README.md
└── tsconfig.json
```

## License

MIT