x-search-mcp
Minimal MCP server for xAI X search using the Responses API and structured outputs.
Features
- Single MCP tool:
x_search - Uses xAI Responses API with
x_searchtool calling - Structured output parsing + citation normalization
Requirements
- Node.js >= 18
XAI_API_KEYenvironment variable
MCP client config
Add the following config to your MCP client:
{
"mcpServers": {
"x-search": {
"command": "npx",
"args": ["-y", "x-search-mcp"],
"env": {
"XAI_API_KEY": "your-key-here"
}
}
}
}
Local development
npm install
npm run build
Smoke test (optional)
XAI_API_KEY=your-key-here npm run build
XAI_API_KEY=your-key-here npm run smoke-test
Note: this test requires network access and may fail in restricted environments.
MCP Tool
x_search
Searches X with optional filters.
Input
{
"query": "string",
"allowed_x_handles": ["string"],
"excluded_x_handles": ["string"],
"from_date": "YYYY-MM-DD",
"to_date": "YYYY-MM-DD",
"enable_image_understanding": true,
"enable_video_understanding": true,
"include_raw_response": false
}
Output
{
"answer": "string",
"citations": ["https://x.com/..."],
"inline_citations": [
{
"url": "https://x.com/...",
"start_index": 10,
"end_index": 42,
"title": "1"
}
],
"raw_response": {}
}
Environment Variables
XAI_API_KEY(required)XAI_MODEL(default:grok-4-1-fast)XAI_BASE_URL(default:https://api.x.ai/v1)XAI_TIMEOUT(default:30000)
Notes
allowed_x_handlesandexcluded_x_handlesare mutually exclusive.- Date filters must be
YYYY-MM-DDandfrom_datemust be <=to_date. - Tool responses are returned as MCP
structuredContent(with a text fallback for display). - Citations are normalized from xAI response annotations when available.