x-mcp

x-mcp

A Model Context Protocol (MCP) server for the X (Twitter) API. Built with the official @xdevplatform/xdk SDK and OAuth 2.0 PKCE authentication.

Features

• 23 tools across users, posts, bookmarks, likes, and lists
• OAuth 2.0 PKCE with automatic token refresh
• Dual output: markdown (human-readable) or JSON (structured)
• MCP tool annotations: readOnlyHint, destructiveHint, idempotentHint

Prerequisites

• Node.js v18+
• pnpm
• X API OAuth 2.0 credentials (Client ID and Secret)

Setup

1. Install dependencies:

   pnpm install

1. Configure environment:

   cp .env.example .env

Edit .env: `` X_CLIENT_ID=your_oauth2_client_id X_CLIENT_SECRET=your_oauth2_client_secret X_REDIRECT_URI=http://localhost:3000/callback ``

1. Authenticate:

   pnpm run setup-auth

1. Build:

   pnpm run build

Getting X API Credentials

1. Go to the X Developer Portal
2. Create a Project and App
3. Enable OAuth 2.0 in app settings
4. Set app type to Web App
5. Add callback URL: http://localhost:3000/callback
6. Copy Client ID and Client Secret from the OAuth 2.0 section

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "x-mcp": {
      "command": "node",
      "args": ["/path/to/x-mcp/dist/index.js"],
      "env": {
        "X_TOKENS_PATH": "/path/to/x-mcp/.tokens.json",
        "X_CLIENT_ID": "your_client_id",
        "X_CLIENT_SECRET": "your_client_secret",
        "X_REDIRECT_URI": "http://localhost:3000/callback"
      }
    }
  }
}

Tools

Users

| Tool | Description | Parameters | |------|-------------|------------| | x_get_user_profile | Fetch a user profile by username | username, response_format | | x_get_my_profile | Get the authenticated user's profile | response_format | | x_get_followers | Get a user's followers | username, limit, response_format | | x_get_following | Get accounts a user follows | username, limit, response_format |

Posts

| Tool | Description | Parameters | |------|-------------|------------| | x_get_user_posts | Fetch recent posts from a user (excludes retweets/replies) | username, limit, response_format | | x_get_my_timeline | Get your home timeline (reverse chronological) | limit, response_format | | x_search_posts | Search recent posts (last 7 days) | query, limit, response_format |

Bookmarks

| Tool | Description | Parameters | |------|-------------|------------| | x_get_my_bookmarks | Fetch your bookmarked posts | limit, response_format | | x_add_bookmark | Bookmark a post | tweet_id | | x_remove_bookmark | Remove a bookmark | tweet_id |

Likes

| Tool | Description | Parameters | |------|-------------|------------| | x_get_my_likes | Fetch your liked posts | limit, response_format | | x_like_post | Like a post | tweet_id | | x_unlike_post | Unlike a post | tweet_id |

Lists

| Tool | Description | Parameters | |------|-------------|------------| | x_get_my_lists | Get your owned lists | response_format | | x_get_list | Get list details by ID | list_id, response_format | | x_get_list_posts | Get posts from a list | list_id, limit, response_format | | x_get_list_members | Get members of a list | list_id, limit, response_format | | x_create_list | Create a new list | name, description, private | | x_update_list | Update a list | list_id, name, description, private | | x_delete_list | Delete a list | list_id | | x_add_list_member | Add a user to a list | list_id, username | | x_remove_list_member | Remove a user from a list | list_id, username |

Project Structure

src/
├── index.ts              # MCP server entry point
├── constants.ts          # Shared constants
├── types.ts              # TypeScript interfaces
├── setup-auth.ts         # OAuth 2.0 setup flow
├── schemas/
│   └── common.ts         # Shared Zod schemas
├── services/
│   ├── auth-manager.ts   # OAuth 2.0 token management
│   └── x-client.ts       # X API client wrapper
├── tools/
│   ├── users.ts          # User profile tools
│   ├── tweets.ts         # Post/timeline tools
│   ├── bookmarks.ts      # Bookmark tools
│   ├── likes.ts          # Like tools
│   └── lists.ts          # List management tools
└── utils/
    └── formatting.ts     # Response formatting helpers

Scripts

| Command | Description | |---------|-------------| | pnpm run build | Compile TypeScript | | pnpm run dev | Run in development mode | | pnpm start | Run compiled server | | pnpm run setup-auth | Authenticate with X | | pnpm run reset-auth | Reset saved tokens |

API Access Tiers

| Tier | What works | |------|-----------| | Free | Post creation, basic read access | | Basic ($200/mo) | All read/write endpoints, followers/following | | Pro ($5,000/mo) | Higher rate limits, full search |

License

MIT