# x-mcp-ai MCP server

> Exposes the X (Twitter) API v2 to MCP clients with policy-gated tools and built-in cost awareness for managing posts, users, and engagement.

- Repository: https://github.com/IvanBBaev/x-mcp
- Page: https://hostedmcp.org/servers/ivanbbaev/x-mcp
- Transport: stdio
- Stars: 1
- License: MIT
- Latest version: 0.8.0

## Install

### Claude Code

```sh
claude mcp add --env 'X_MCP_BEARER_TOKEN=<YOUR_X_MCP_BEARER_TOKEN>' --env 'X_MCP_CLIENT_SECRET=<YOUR_X_MCP_CLIENT_SECRET>' x-mcp -- npx -y x-mcp-ai
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "x-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "x-mcp-ai"
      ],
      "env": {
        "X_MCP_BEARER_TOKEN": "<YOUR_X_MCP_BEARER_TOKEN>",
        "X_MCP_CLIENT_SECRET": "<YOUR_X_MCP_CLIENT_SECRET>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "x-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "x-mcp-ai"
      ],
      "env": {
        "X_MCP_BEARER_TOKEN": "<YOUR_X_MCP_BEARER_TOKEN>",
        "X_MCP_CLIENT_SECRET": "<YOUR_X_MCP_CLIENT_SECRET>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"x-mcp","type":"stdio","command":"npx","args":["-y","x-mcp-ai"],"env":{"X_MCP_BEARER_TOKEN":"<YOUR_X_MCP_BEARER_TOKEN>","X_MCP_CLIENT_SECRET":"<YOUR_X_MCP_CLIENT_SECRET>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "x-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "x-mcp-ai"
      ],
      "env": {
        "X_MCP_BEARER_TOKEN": "<YOUR_X_MCP_BEARER_TOKEN>",
        "X_MCP_CLIENT_SECRET": "<YOUR_X_MCP_CLIENT_SECRET>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add x-mcp --env 'X_MCP_BEARER_TOKEN=<YOUR_X_MCP_BEARER_TOKEN>' --env 'X_MCP_CLIENT_SECRET=<YOUR_X_MCP_CLIENT_SECRET>' -- npx -y x-mcp-ai
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.x-mcp]
command = "npx"
args = ["-y", "x-mcp-ai"]

[mcp_servers.x-mcp.env]
X_MCP_BEARER_TOKEN = "<YOUR_X_MCP_BEARER_TOKEN>"
X_MCP_CLIENT_SECRET = "<YOUR_X_MCP_CLIENT_SECRET>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'X_MCP_BEARER_TOKEN=<YOUR_X_MCP_BEARER_TOKEN>' -e 'X_MCP_CLIENT_SECRET=<YOUR_X_MCP_CLIENT_SECRET>' x-mcp npx -- -y x-mcp-ai
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "x-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "x-mcp-ai"
      ],
      "env": {
        "X_MCP_BEARER_TOKEN": "<YOUR_X_MCP_BEARER_TOKEN>",
        "X_MCP_CLIENT_SECRET": "<YOUR_X_MCP_CLIENT_SECRET>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `X_MCP_BEARER_TOKEN` | no | yes | Application-only bearer token (app-only mode). |
| `X_MCP_CLIENT_SECRET` | no | yes | OAuth 2.0 client secret (confidential clients only). |
| `X_MCP_AUTH_MODE` | no | no | Authentication mode: oauth2 (default) or app-only. |
| `X_MCP_AVAILABILITY` | no | no | Comma-separated specially-provisioned access classes to declare: pilot, premium-user, enterprise. Unset means the conservative default (app+user, user-only). |
| `X_MCP_BUDGET_MODE` | no | no | Budget enforcement: warn (default) or hard. |
| `X_MCP_CLIENT_ID` | no | no | OAuth 2.0 client ID (oauth2 mode). |
| `X_MCP_CREDIT_BUDGET` | no | no | Session spend cap in USD. |
| `X_MCP_HIDE_DENIED` | no | no | Set to 1 to drop policy-denied tools from registration entirely instead of registering them annotated as denied. |
| `X_MCP_LOG_LEVEL` | no | no | Diagnostic verbosity on stderr: silent, error, info (default), or debug. |
| `X_MCP_MEDIA_DIR` | no | no | Directory uploads must resolve inside. Media upload is disabled unless this is set. |
| `X_MCP_POLICY` | no | no | Policy preset: read-only (default), engage, publish, manage, or full. |
| `X_MCP_POLICY_ALLOW` | no | no | Comma-separated op:domain cells to allow on top of the preset (e.g. read:dm,write:dm). |
| `X_MCP_POLICY_DENY` | no | no | Comma-separated op:domain cells to deny; deny beats allow beats preset. |
| `X_MCP_PROFILE` | no | no | Name of the profile to select from the profiles file. |
| `X_MCP_PROFILES_FILE` | no | no | Path to a profiles file holding named configuration blocks. |
| `X_MCP_TIMEOUT_MS` | no | no | Per-HTTP-request timeout in milliseconds (default 30000). |
| `X_MCP_TOKEN_FILE` | no | no | Path to the rotating OAuth 2.0 token store (default: OS-resolved). |
| `X_MCP_TOKEN_KEYCHAIN` | no | no | Set to 1 to keep OAuth 2.0 tokens in the OS keychain (macOS, Linux) instead of a token file. Mutually exclusive with an explicit X_MCP_TOKEN_FILE. |

## Tools (11)

- `auth`
- `usage`
- `posts`
- `search`
- `archive`
- `timelines`
- `engagement`
- `users`
- `graph`
- `lists`
- `media`

## FAQ

### How does the server handle X API costs?

The server is aware of pay-per-use pricing and reports the cost of every result. You can set a session spend cap using X_MCP_CREDIT_BUDGET to prevent overspending.

### What are the available permission levels?

The server uses a two-axis policy model with five presets: read-only, engage, publish, manage, and full. Direct-message access is never included in a preset and must be explicitly allowed.

### What authentication methods are supported?

It supports OAuth 2.0 PKCE for user context with automatic token refreshing, and an app-only bearer token mode for read-only deployments.
