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
• An xAI account eligible for OAuth API access, or an xAI API key
• An MCP client such as Codex or Claude Code

Installation

Clone the repository and install the command with uv:

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

For local development, use uv sync instead:

uv sync

Authentication

Device-code OAuth

Run the login command once:

x-search-mcp login

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

~/.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:

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:

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 .:

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

For a development checkout, use the included launcher:

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:

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

For a development checkout:

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:

x-search-mcp serve

/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:

{
  "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:

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:

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.

Acknowledgments

• xAI Search tools
• Model Context Protocol
• OpenAI: Build an MCP server