# x-search-mcp

A self-contained Model Context Protocol (MCP) server that gives Codex, Claude Code, and other MCP clients access to xAI's built-in X Search.

It calls xAI's Responses API with the server-side `x_search` tool. The result is a Grok-generated research answer with citations from X, rather than a raw firehose or a replacement for the official X API.

## Features

- Search current X posts, profiles, and threads with natural-language queries.
- Include or exclude specific X handles.
- Restrict searches to a date range.
- Optionally analyze images and videos attached to matching posts.
- Return both top-level and inline citation metadata.
- Mark filtered responses as `degraded` when xAI returns no citations.
- Authenticate with standalone xAI device-code OAuth or `XAI_API_KEY`.
- Refresh rotating OAuth tokens automatically with a cross-process file lock.
- Expose a narrow, read-only stdio MCP surface containing one tool: `x_search`.

## Requirements

- Python 3.11 or newer
- [uv](https://docs.astral.sh/uv/)
- An xAI account eligible for OAuth API access, or an [xAI API key](https://console.x.ai/)
- An MCP client such as [Codex](https://developers.openai.com/codex/mcp/) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp)

## Installation

Clone the repository and install the command with `uv`:

```bash
git clone https://github.com/kamellperry/x-search-mcp.git
cd x-search-mcp
uv tool install .
```

For local development, use `uv sync` instead:

```bash
uv sync
```

## Authentication

### Device-code OAuth

Run the login command once:

```bash
x-search-mcp login
```

The command opens xAI's device authorization page, waits for approval, and stores the resulting tokens in:

```text
~/.config/x-search-mcp/auth.json
```

The auth directory and token file are created with user-only permissions. The server refreshes expiring access tokens automatically and persists rotated refresh tokens atomically. It does not read Hermes, Codex, Claude, browser, or shell credential stores.

Check credential state without printing any token:

```bash
x-search-mcp status
```

OAuth access depends on xAI account tier and entitlement. If xAI rejects OAuth API access, use an API key instead.

### API key fallback

Set an xAI API key in the environment that launches the MCP server:

```bash
export XAI_API_KEY="your-api-key"
```

Stored OAuth is preferred when both credential methods are present.

## Connect an MCP client

### Codex

If the command was installed with `uv tool install .`:

```bash
codex mcp add x-search -- x-search-mcp serve
codex mcp get x-search
```

For a development checkout, use the included launcher:

```bash
codex mcp add x-search -- /absolute/path/to/x-search-mcp/run-server
```

Then start a fresh Codex session so it receives the new tool manifest.

### Claude Code

If the command was installed globally:

```bash
claude mcp add --scope user x-search -- x-search-mcp serve
claude mcp get x-search
```

For a development checkout:

```bash
claude mcp add --scope user x-search -- /absolute/path/to/x-search-mcp/run-server
```

### Other MCP clients

Configure a stdio server with either of these commands:

```text
x-search-mcp serve
```

```text
/absolute/path/to/x-search-mcp/run-server
```

Do not run the stdio server through a wrapper that writes ordinary output to stdout. MCP protocol messages use stdout; diagnostics belong on stderr.

## Tool reference

### `x_search`

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Natural-language description of what to find on X. |
| `allowed_x_handles` | string[] | no | Search only these handles, maximum 10. Leading `@` is optional. |
| `excluded_x_handles` | string[] | no | Exclude these handles, maximum 10. Cannot be combined with `allowed_x_handles`. |
| `from_date` | string | no | Inclusive start date in `YYYY-MM-DD` format. |
| `to_date` | string | no | End date in `YYYY-MM-DD` format. |
| `enable_image_understanding` | boolean | no | Ask xAI to inspect images attached to matching posts. |
| `enable_video_understanding` | boolean | no | Ask xAI to inspect videos attached to matching posts. |

Example tool arguments:

```json
{
  "query": "What has xAI announced recently?",
  "allowed_x_handles": ["xai"],
  "from_date": "2026-07-01"
}
```

The result includes:

- `answer`: synthesized answer from the configured Grok model
- `citations`: citations returned at the response level
- `inline_citations`: URL annotations attached to generated text
- `credential_source`: `xai-oauth` or `xai-api-key`
- `degraded`: true when narrowing filters were active but no citations were returned
- `degraded_reason`: explanation when `degraded` is true

Treat a degraded answer as unsourced model output. Broaden the filters, retry, or verify the claim another way.

## Configuration

| Environment variable | Default | Description |
| --- | --- | --- |
| `X_SEARCH_MCP_HOME` | `~/.config/x-search-mcp` | Directory containing the standalone OAuth state and lock. |
| `X_SEARCH_MODEL` | `grok-4.5` | xAI model used for the Responses API request. |
| `X_SEARCH_REASONING_EFFORT` | unset | Optional `low`, `medium`, `high`, or `xhigh`. |
| `X_SEARCH_TIMEOUT_SECONDS` | `180` | HTTP request timeout, clamped to at least 30 seconds. |
| `XAI_API_KEY` | unset | Optional API-key fallback when standalone OAuth is unavailable. |

## Security notes

- `auth.json`, `.env` files, virtual environments, caches, and build outputs are ignored by Git.
- OAuth and inference endpoints are restricted to HTTPS hosts on the `x.ai` domain.
- The inference bearer is sent only to `https://api.x.ai/v1`.
- The status command reports metadata only and never prints tokens.
- Refresh tokens may rotate after each refresh. Do not copy one OAuth token store between concurrently running installations.
- Never commit `~/.config/x-search-mcp/auth.json` or pass its contents to an MCP client configuration.

## Troubleshooting

### `No xAI credentials`

Run `x-search-mcp login`, or provide `XAI_API_KEY` to the MCP server process.

### OAuth login succeeds but API calls are denied

xAI may restrict OAuth API access by subscription tier. Configure `XAI_API_KEY` if your account is not entitled to OAuth API access.

### The MCP client does not show `x_search`

1. Run `x-search-mcp status`.
2. Run the client's MCP inspection command, such as `codex mcp get x-search`.
3. Use an absolute launcher path if the client does not inherit your shell `PATH`.
4. Restart the client so it reloads the MCP tool manifest.

### A filtered result is marked degraded

xAI returned a synthesized response without citations matching the requested handle or date filters. Remove or broaden filters and retry.

## Development

Install development dependencies and run the complete test suite:

```bash
uv sync
uv run ruff check src tests
uv run ruff format --check src tests
uv run pytest
uv run python tests/mcp_smoke.py
```

The smoke test starts the real stdio server, initializes an MCP client session, and confirms that `x_search` is discoverable with the expected schema.

Build distribution artifacts with:

```bash
uv build
```

## Project scope

This project intentionally exposes X Search only. It does not post, like, follow, send messages, or mutate an X account. It does not provide deterministic raw-post pagination or full X API semantics.

## License

MIT. See [LICENSE](LICENSE).

## Acknowledgments

- [xAI Search tools](https://docs.x.ai/docs/guides/tools/search-tools)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [OpenAI: Build an MCP server](https://developers.openai.com/plugins/build/mcp-server)