# 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_search` tool calling
- Structured output parsing + citation normalization
## Requirements
- Node.js >= 18
- `XAI_API_KEY` environment variable
## MCP client config
Add the following config to your MCP client:
```json
{
"mcpServers": {
"x-search": {
"command": "npx",
"args": ["-y", "x-search-mcp"],
"env": {
"XAI_API_KEY": "your-key-here"
}
}
}
}
```
## Local development
```bash
npm install
npm run build
```
## Smoke test (optional)
```bash
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**
```json
{
"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**
```json
{
"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_handles` and `excluded_x_handles` are mutually exclusive.
- Date filters must be `YYYY-MM-DD` and `from_date` must 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.
