x-handle-mcp

MCP server for checking X/Twitter handle availability and status with 100% accuracy.

What It Does

Handle Availability (Can I Register This?)

Checks if a handle is available for registration. Uses X's internal authenticated API - the same one used when you change your username in settings.

| Result | Meaning | |--------|---------| | available: true | You can register this handle | | available: false | Handle is taken (by active, suspended, reserved, or deactivated account) |

Requires authentication - you need to provide your X session cookies.

Handle Status (Is This Account Active?)

Checks if an X/Twitter account is active (exists and is functional).

| Status | Meaning | isActive | |--------|---------|------------| | active | Account exists and is functional | true | | protected | Account exists but is private | true | | suspended | Account was suspended by X | false | | not_found | Account doesn't exist | false | | withheld | Account is withheld in your region | false |

Installation

npm install x-handle-mcp

Or run directly:

npx x-handle-mcp

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | X_AUTH_TOKEN | For availability | auth_token cookie from X (get from browser) | | X_CSRF_TOKEN | For availability | ct0 cookie from X (get from browser) | | X_BEARER_TOKEN | For status | X API v2 Bearer Token | | X_USE_GRAPHQL_FALLBACK | No | Enable fallback methods (default: true) | | X_HTTP_TIMEOUT | No | HTTP timeout in ms (default: 30000) |

Getting X Session Cookies (For Availability Checking)

1. Log into X in your browser
2. Open DevTools (F12) → Application → Cookies → https://x.com
3. Copy these cookie values:
   • auth_token → X_AUTH_TOKEN
   • ct0 → X_CSRF_TOKEN

Note: Session cookies expire periodically. You may need to refresh them.

Getting an X API Bearer Token (For Status Checking)

1. Go to developer.x.com
2. Create a new app (Free tier works)
3. Generate a Bearer Token
4. Set X_BEARER_TOKEN environment variable

MCP Tools

check_x_handle_availability

Check if a handle is available for registration (100% accurate).

Input:

{
  "handle": "coolhandle123"
}

Output:

{
  "handle": "coolhandle123",
  "available": true,
  "suggestions": [],
  "checkedAt": "2025-01-15T10:30:00.000Z",
  "method": "authenticated_graphql",
  "confidence": "high"
}

Or if taken:

{
  "handle": "elonmusk",
  "available": false,
  "suggestions": ["elonmusk123", "elonmusk_x", "elonmuskfan"],
  "checkedAt": "2025-01-15T10:30:00.000Z",
  "method": "authenticated_graphql",
  "confidence": "high"
}

check_x_handles_availability_bulk

Check multiple handles at once (max 100).

Input:

{
  "handles": ["available123", "elonmusk", "test_handle"]
}

Output:

{
  "results": [...],
  "summary": {
    "total": 3,
    "available": 1,
    "unavailable": 2
  },
  "checkedAt": "2025-01-15T10:30:00.000Z"
}

check_x_handle

Check a single handle's active status.

Input:

{
  "handle": "elonmusk"
}

Output:

{
  "handle": "elonmusk",
  "isActive": true,
  "state": "active",
  "reason": "Account exists and is active",
  "canInteract": true,
  "metadata": {
    "checkedAt": "2025-01-15T10:30:00.000Z",
    "method": "api_v2",
    "confidence": "high"
  },
  "userData": {
    "id": "44196397",
    "name": "Elon Musk",
    "username": "elonmusk"
  }
}

check_x_handles_bulk

Check multiple handles' status at once (max 100).

MCP Configuration

With Availability Checking (Recommended)

{
  "mcpServers": {
    "x-handle": {
      "command": "npx",
      "args": ["x-handle-mcp"],
      "env": {
        "X_AUTH_TOKEN": "your-auth-token-cookie",
        "X_CSRF_TOKEN": "your-ct0-cookie"
      }
    }
  }
}

With Both Features

{
  "mcpServers": {
    "x-handle": {
      "command": "npx",
      "args": ["x-handle-mcp"],
      "env": {
        "X_AUTH_TOKEN": "your-auth-token-cookie",
        "X_CSRF_TOKEN": "your-ct0-cookie",
        "X_BEARER_TOKEN": "your-api-bearer-token"
      }
    }
  }
}

Status-Only Mode (No Auth Needed)

{
  "mcpServers": {
    "x-handle": {
      "command": "npx",
      "args": ["x-handle-mcp"],
      "env": {
        "X_USE_GRAPHQL_FALLBACK": "true"
      }
    }
  }
}

Rate Limits

• Availability API (authenticated): ~50 requests / 15 minutes
• API v2 (with Bearer Token): 300 requests / 15 minutes
• Syndication (unauthenticated): ~50-100 requests before soft-limiting

How 100% Accuracy Works

Availability Checking

Uses X's internal GetUsernameAvailabilityAndSuggestions GraphQL endpoint - the exact same API X uses when you change your username in settings. This returns a definitive boolean available field.

Status Checking

The X API v2 returns different error structures for different states:

• Active accounts → Returns user data object
• Suspended accounts → Returns 200 with "Forbidden" error containing "suspended"
• Not found → Returns 200 with "Not Found" error

This allows definitive state detection with no false positives.

License

MIT