xai-search-mcp
You can use this MCP server to run real-time web and X (Twitter) searches via the xAI API, returning cited results.
web_search: search the web in real-time with optional domain allow/exclude filters (max 5 each; cannot combine allow and exclude).x_search: search X posts, users, and threads with optional handle allow/exclude filters (max 10 each; cannot combine allow and exclude) andfrom_date/to_daterange filters.Queries are required, trimmed, and must not be empty.
Results include source citations extracted from xAI response annotations.
Can be run via
npxor a local build by settingXAI_API_KEY; optionalXAI_MODELandXAI_TIMEOUT_MSare configurable.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@xai-search-mcp search the web for recent breakthroughs in quantum computing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
xAI Search MCP Server
An MCP (Model Context Protocol) server that provides real-time web search and X (Twitter) search capabilities via the xAI API.
Quick Start
Requires Node.js 22 or newer. The easiest way to use this server is via npx — no clone or build required:
XAI_API_KEY=your_key npx @kicito/xai-search-mcpOn Windows PowerShell:
$env:XAI_API_KEY = "your_key"
npx @kicito/xai-search-mcpJust set your XAI_API_KEY environment variable and configure your MCP client (see Configuration below).
Related MCP server: superhighway-mcp
Tools
web_search
Search the web in real-time. Returns results with source citations.
Parameter | Type | Required | Description |
| string | ✅ | The search query; trimmed and must not be empty |
| string[] | ❌ | Only search within these domains (max 5) |
| string[] | ❌ | Exclude these domains from search (max 5) |
x_search
Search X (Twitter) posts, users, and threads. Returns results with source citations.
Parameter | Type | Required | Description |
| string | ✅ | The search query for X posts; trimmed and must not be empty |
| string[] | ❌ | Only consider posts from these handles (max 10) |
| string[] | ❌ | Exclude posts from these handles (max 10) |
| string | ❌ | Inclusive start date (valid calendar date in |
| string | ❌ | Exclusive end date (valid calendar date in |
Input validation
Queries are trimmed; empty or whitespace-only queries are rejected.
Domains are trimmed, lowercased and IDNA-normalized, with a trailing root dot removed. Supply bare domains (for example,
example.com) rather than URLs. Empty or invalid entries are rejected.X handles are trimmed and a leading
@is removed. Handles must contain 1–15 letters, digits or underscores; case is preserved. Profile URLs are not accepted.For each tool, nonempty allow and exclude lists cannot be combined. Empty filter arrays (and
nullor omitted filters) are treated as absent.Dates must be real calendar dates in exactly
YYYY-MM-DDformat, not timestamps. When both dates are provided,from_datemust be on or beforeto_date.
X handle/date filters apply to search, not thread fetches. Handle lists are conservatively capped at 10 entries.
Setup
Prerequisites
Node.js 22 or newer
An xAI API key
Install & Build
npm ci
npm run buildRun these commands from a cloned checkout. The build uses TypeScript and a Node.js helper, with no POSIX chmod command required; it works on Linux, macOS, and Windows.
Configuration
OpenCode V2 (MCP server and optional agent skill)
The optional xai-search skill tells OpenCode agents when and how to use web_search and x_search, including filters and source citations. It is guidance, not an executable tool or an MCP server. In this checkout, OpenCode can load the skill from .opencode/skills/xai-search/SKILL.md. To use it in another project, copy the xai-search skill directory to ~/.config/opencode/skills/xai-search/ for your user, or to that project's .opencode/skills/xai-search/.
Configure the MCP server separately. With Node.js 22+ and an xAI API key, put the following in your OpenCode opencode.jsonc (merge with any existing config):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"xai-search": {
"type": "local",
"command": ["npx", "-y", "@kicito/xai-search-mcp"],
"environment": {
"XAI_API_KEY": "{env:XAI_API_KEY}"
}
}
}
}
}Set XAI_API_KEY in the environment that launches OpenCode; do not commit your key to git. Check the server connection with opencode mcp list. The skill alone cannot supply the server or API key. This OpenCode V2 config uses mcp.servers, not the mcpServers format shown below for Claude Desktop and Cursor.
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"xai-search": {
"command": "npx",
"args": ["-y", "@kicito/xai-search-mcp"],
"env": {
"XAI_API_KEY": "your-xai-api-key-here"
}
}
}
}Cursor
Add to your Cursor MCP settings:
{
"mcpServers": {
"xai-search": {
"command": "npx",
"args": ["-y", "@kicito/xai-search-mcp"],
"env": {
"XAI_API_KEY": "your-xai-api-key-here"
}
}
}
}If you prefer to clone and build manually:
git clone https://github.com/kicito/x_search_mcp.git
cd x_search_mcp
npm ci
npm run buildThen use the full path in your config:
{
"mcpServers": {
"xai-search": {
"command": "node",
"args": ["/absolute/path/to/x_search_mcp/build/index.js"],
"env": {
"XAI_API_KEY": "your-xai-api-key-here"
}
}
}
}Environment Variables
Variable | Required | Default | Description |
| ✅ | — | Your xAI API key |
| ❌ |
| The xAI model to use |
| ❌ |
| Application request timeout in milliseconds; positive integer, maximum |
Requests are bounded by the application timeout, including response-body processing. MCP request cancellation aborts the upstream request and stops processing without a response. Timeouts and upstream failures return tool errors; upstream error details are sanitized and bounded rather than returning arbitrary raw response bodies. Requests are not automatically retried.
How It Works
The server uses the xAI Responses API with built-in server-side tools (web_search and x_search). When an MCP client calls one of the tools, the server:
Sends the query to
POST https://api.x.ai/v1/responseswith the appropriate tool configurationGrok executes the search, gathers results, and generates a response
Citations (source URLs) are extracted from the response annotations
The response text and formatted citations are returned to the MCP client
Development
# Install the locked dependencies
npm ci
# Type-check without emitting build output
npm run typecheck
# Build
npm run build
# Build and run offline tests
npm test
# Build and verify npm package contents and executable metadata (offline dry-run)
npm run test:package
# Start after setting XAI_API_KEY in your shell or MCP client
npm startnpm run check:package checks an existing build without rebuilding. Package checks verify the CLI entrypoint, executable metadata, build files, README, manifest, and MIT license using npm pack --dry-run --json; they do not publish or require an API key. Tests use mocked requests, not live xAI searches.
CI runs type-checking, tests, and package checks on Node.js 22 and 24 on Linux, plus Node.js 22 on Windows. Tag-triggered npm publishing is gated on the same checks and uses Node.js 22.
License
MIT — see LICENSE.
Available Tools
2 toolsweb_searchB
Search the web in real-time using xAI. Returns results with source citations.
Inputs: query (required), allowed_domains, excluded_domains.
x_searchA
Search X (Twitter) posts, users, and threads in real-time using xAI. Returns results with source citations.
Inputs: query (required), to_date, from_date, allowed_x_handles, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools target completely distinct domains: web_search is for general web content, while x_search is specifically for X (Twitter). There is no overlap in their search scopes, so an agent can easily distinguish between them.
Both tools use a consistent verb_noun pattern (web_search, x_search), with the verb 'search' followed by a clear domain identifier. The naming is uniform and predictable.
With only 2 tools, the server is minimal but justified for its focused purpose of providing real-time search across two specific sources (web and X). It could potentially include more search types, but the current count is reasonable for a specialized search server.
The server covers the primary search needs implied by its name: web and X/Twitter searches. Minor gaps like additional search options or filters are missing, but the core functionality is adequately addressed for basic real-time searches.
Maintenance
Related MCP Connectors
Web search API and MCP server for developers building AI agents.
Hosted X (Twitter) MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Official MCP server for twitterapis.com. Twitter/X search, users, DMs, Grok, monitoring and writes.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to perform search-augmented queries and deep multi-source research using the Perplexity API.26Apache 2.0
- AlicenseAqualityFmaintenanceAn MCP server that provides real-time web search to AI agents via a pay-per-search USDC microtransaction system.573 npm1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for internet search via direct Google and DuckDuckGo HTML scraping with AI-powered result normalization and optional summarization, requiring no API keys for search.MIT
- AlicenseBqualityDmaintenanceMCP server providing search, extract, map, and crawl tools powered by Tavily for real-time web data access.440 npmMIT