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

Create a X Developer account
Create a new app in the Developer Portal
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)
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:

Open your browser to X's authorization page
Start a local callback server
Exchange the authorization code for tokens
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)

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

Multi-User Testing (V2.0)

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

Legacy Testing (V1.0)

Authentication: npm run auth
Start legacy server: npm run start:legacy
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

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

Create a X Developer account
Create a new app in the Developer Portal
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)
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:

Open your browser to X's authorization page
Start a local callback server
Exchange the authorization code for tokens
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)

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

Multi-User Testing (V2.0)

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

Legacy Testing (V1.0)

Authentication: npm run auth
Start legacy server: npm run start:legacy
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