X MCP Server v2.0

A comprehensive Model Context Protocol (MCP) server for X (Twitter) API v2 with multi-user OAuth 2.0 + PKCE, encrypted token storage, and automatic token refresh.

🚀 New in v2.0

• ✅ Multi-User Support - Multiple users with isolated tokens and sessions
• ✅ Dual OAuth Flows - Loopback (local) + Hosted Pairing Code (remote/multi-user)
• ✅ Encrypted Token Storage - SQLite database with OS keychain integration
• ✅ Automatic Token Refresh - Background refresh with scope validation
• ✅ Session Management - Secure session handling for different transports
• ✅ Non-Browser Support - Works without browser access via pairing codes

Features

• ✅ OAuth 2.0 Authorization Code + PKCE authentication (both flows)
• ✅ Multi-user support with per-user token isolation
• ✅ Encrypted local token storage (AES-256 + OS keychain)
• ✅ Automatic token refresh and persistence
• ✅ Scope verification and re-auth instructions
• ✅ Rate limiting with retry/backoff logic
• ✅ Bookmark management (list, add, remove)
• ✅ Tweet creation (text, media, replies, quotes)
• ✅ Session-aware MCP resources
• ✅ Comprehensive error handling and logging

Setup

1. X Developer Account Setup

1. Create a X Developer account
2. Create a new app in the Developer Portal
3. Configure OAuth 2.0 settings:
   • App permissions: Read and Write
   • Type of App: Web App
   • Callback URI: http://localhost:3000/callback (or your custom URI)
   • Website URL: Required (can be placeholder)
4. Note your Client ID and Client Secret

2. Installation

# Clone or create the project directory
cd x-mcp
npm install
npm run build

3. Environment Setup

Create a .env file or export environment variables:

export X_CLIENT_ID="your_client_id_here"
export X_CLIENT_SECRET="your_client_secret_here"
export X_REDIRECT_URI="http://localhost:3000/callback"  # Optional

4. Authentication

Run the authentication helper to complete OAuth flow:

npm run auth
# or
node dist/auth-helper.js

This will:

1. Open your browser to X's authorization page
2. Start a local callback server
3. Exchange the authorization code for tokens
4. Save tokens to ~/.x-mcp/tokens.json

Quick Start

V2.0 Multi-User Server (Recommended)

npm install
npm run build

# Set environment variables
export X_CLIENT_ID="your_client_id"
export X_CLIENT_SECRET="your_client_secret"

# Start multi-user server
npm start

Authentication Flows

Local/Single-User (Loopback)

# Via MCP tool call
{"method": "tools/call", "params": {"name": "auth/start", "arguments": {"mode": "loopback"}}}
# Opens browser for authorization

Multi-User/Remote (Hosted Pairing)

# Enable hosted mode
export X_HOSTED_MODE="true"
export X_BASE_URL="https://yourapp.com"

# Via MCP tool call  
{"method": "tools/call", "params": {"name": "auth/start", "arguments": {"mode": "hosted"}}}
# Returns pairing code + login URL

# Check status
{"method": "tools/call", "params": {"name": "auth/status", "arguments": {"pairing_code": "ABC12345"}}}

Legacy V1.0 Server

npm run start:legacy
# or
node dist/index.js

MCP Tools

The server provides these tools:

bookmarks.list

List user bookmarks with pagination support.

Parameters:

• user_id (optional): User ID (defaults to authenticated user)
• max_results (optional): Maximum results per page (1-100, default: 10)
• pagination_token (optional): Token for next page of results

Example:

{
  "tweets": [
    {
      "id": "1234567890",
      "text": "Great tweet content...",
      "created_at": "2023-01-01T00:00:00.000Z",
      "author_id": "987654321",
      "public_metrics": {
        "retweet_count": 5,
        "like_count": 10,
        "reply_count": 2,
        "quote_count": 1
      }
    }
  ],
  "nextToken": "next_page_token"
}

bookmarks.add

Add a tweet to bookmarks.

Parameters:

• tweet_id (required): ID of the tweet to bookmark
• user_id (optional): User ID (defaults to authenticated user)

Returns: { "ok": true }

bookmarks.remove

Remove a tweet from bookmarks.

Parameters:

• tweet_id (required): ID of the tweet to remove from bookmarks
• user_id (optional): User ID (defaults to authenticated user)

Returns: { "ok": true }

tweet.create

Create a new tweet.

Parameters:

• text (required): Tweet text content (max 280 characters)
• media_ids (optional): Array of media IDs to attach
• reply (optional): Object with in_reply_to_tweet_id for replies
• quote_tweet_id (optional): ID of tweet to quote

Example:

{
  "id": "1234567890",
  "createdAt": "2023-01-01T00:00:00.000Z"
}

MCP Resources

mcp://x/user/me

Current authenticated X user information:

{
  "id": "123456789",
  "username": "example_user",
  "name": "Example User"
}

mcp://x/bookmarks/latest

Last fetched bookmarks page with pagination token:

{
  "tweets": [...],
  "nextToken": "pagination_token"
}

Required Scopes

The server requires these X API scopes:

• bookmark.read or bookmarks.read - Read bookmarks
• bookmarks.write - Modify bookmarks
• tweet.write - Post tweets
• tweet.read - Read tweets (for tweet creation responses)
• users.read - Read user information
• offline.access - Refresh token support

If scopes are missing, the server will provide re-authentication instructions.

Rate Limiting

The server automatically handles X API rate limits:

• ✅ Retries on 429/5xx responses with exponential backoff
• ✅ Reads x-rate-limit-* headers for intelligent throttling
• ✅ Surfaces MCP notifications when limits are low
• ✅ Adapts to actual API limits (doesn't hardcode limits)

Current typical limits (may vary by plan):

• GET bookmarks: ~180 requests per 15 minutes
• POST/DELETE bookmarks: ~50 requests per 15 minutes
• POST tweets: ~300 requests per 15 minutes

File Structure

src/
├── index.ts          # Main MCP server
├── auth.ts           # OAuth 2.0 + PKCE implementation
├── auth-helper.ts    # Interactive authentication flow
├── x-client.ts       # X API client with bookmarks/tweets
├── http-client.ts    # HTTP client with retry/rate limiting
├── storage.ts        # Token persistence
└── types.ts          # TypeScript type definitions

Scripts

npm run build          # Compile TypeScript
npm start              # Start v2.0 multi-user server  
npm run start:legacy   # Start v1.0 legacy server
npm run auth           # Interactive OAuth helper (legacy)
npm test               # Run comprehensive test suite
npm run dev            # Development mode
npm run watch          # Watch mode compilation

Configuration

V2.0 Environment Variables:

• X_CLIENT_ID - X app client ID (required)
• X_CLIENT_SECRET - X app client secret (required)
• X_REDIRECT_URI - OAuth redirect URI (default: http://127.0.0.1:3000/auth/x/cb)
• X_HOSTED_MODE - Enable hosted pairing mode (true/false)
• X_BASE_URL - Base URL for hosted mode (e.g., https://yourapp.com)
• X_MCP_ENCRYPTION_KEY - Manual encryption key (base64, optional)

Storage Locations:

• V2.0 Database: ~/.mcp/x/tokens.db (SQLite with encryption)
• V1.0 Tokens: ~/.x-mcp/tokens.json (legacy JSON format)
• Encryption Key: OS Keychain or ~/.mcp/x/.encryption_key

Error Handling

The server provides detailed error messages for:

• ❌ Missing authentication/tokens
• ❌ Insufficient scopes with re-auth instructions
• ❌ API errors with request IDs (in debug mode)
• ❌ Rate limit violations with retry guidance
• ❌ Network errors with retry logic

Testing

Comprehensive Test Suite

npm test  # Runs all tests including encryption, database, OAuth flows

Manual E2E Testing (V2.0)

1. Start server: npm start
2. Loopback auth: Call auth/start with mode: "loopback"
3. Complete OAuth: Open returned URL, authorize
4. Test bookmarks: bookmarks.list, bookmarks.add, bookmarks.remove
5. Test tweets: tweet.create

Multi-User Testing (V2.0)

1. Enable hosted mode: Set X_HOSTED_MODE=true, X_BASE_URL
2. Start pairing: Call auth/start with mode: "hosted"
3. Complete auth: Visit login URL with pairing code
4. Check status: Call auth/status with pairing code
5. Test with session: Include session context in subsequent calls

Legacy Testing (V1.0)

1. Authentication: npm run auth
2. Start legacy server: npm run start:legacy
3. Test tools: Use existing MCP tools

Troubleshooting

Authentication Issues

• Verify X_CLIENT_ID and X_CLIENT_SECRET are correct
• Check that redirect URI matches your app configuration
• Ensure your X app has correct permissions (Read and Write)

Scope Issues

• Re-run npm run auth to get updated scopes
• Check that your X app is configured for the required permissions

Rate Limit Issues

• The server will automatically retry and backoff
• Check the logs for rate limit information
• Consider the plan limits for your X developer account

Token Issues

• Tokens are auto-refreshed when expired
• V2.0: Check database at ~/.mcp/x/tokens.db, run npm test for diagnostics
• V1.0: Delete ~/.x-mcp/tokens.json and re-authenticate if needed

📚 Detailed Documentation

For comprehensive documentation on the new multi-user OAuth system, architecture, and advanced usage, see:

README-MULTIUSER.md - Complete v2.0 documentation with:

• 🏗️ Detailed architecture overview
• 🔐 Security implementation details
• 🗄️ Database schema and design
• 📡 Complete API reference
• 🧪 Advanced testing scenarios
• 🛠️ Development and extension guide