Skip to main content
Glama
kicito

xai-search-mcp

by kicito
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

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-mcp

On Windows PowerShell:

$env:XAI_API_KEY = "your_key"
npx @kicito/xai-search-mcp

Just 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

query

string

✅

The search query; trimmed and must not be empty

allowed_domains

string[]

❌

Only search within these domains (max 5)

excluded_domains

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

query

string

✅

The search query for X posts; trimmed and must not be empty

allowed_x_handles

string[]

❌

Only consider posts from these handles (max 10)

excluded_x_handles

string[]

❌

Exclude posts from these handles (max 10)

from_date

string

❌

Inclusive start date (valid calendar date in YYYY-MM-DD, e.g. 2025-01-01)

to_date

string

❌

Exclusive end date (valid calendar date in YYYY-MM-DD, e.g. 2025-06-01)

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 null or omitted filters) are treated as absent.

  • Dates must be real calendar dates in exactly YYYY-MM-DD format, not timestamps. When both dates are provided, from_date must be on or before to_date.

X handle/date filters apply to search, not thread fetches. Handle lists are conservatively capped at 10 entries.

Setup

Prerequisites

Install & Build

npm ci
npm run build

Run 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 build

Then 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

XAI_API_KEY

✅

—

Your xAI API key

XAI_MODEL

❌

grok-4-1-fast-reasoning

The xAI model to use

XAI_TIMEOUT_MS

❌

120000

Application request timeout in milliseconds; positive integer, maximum 2147483647

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:

  1. Sends the query to POST https://api.x.ai/v1/responses with the appropriate tool configuration

  2. Grok executes the search, gathers results, and generates a response

  3. Citations (source URLs) are extracted from the response annotations

  4. 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 start

npm 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 tools

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.3
    • First observedweb_search
    • First observedx_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count4/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • perplexity-mcp-server

    cyanheads
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that enables AI agents to perform search-augmented queries and deep multi-source research using the Perplexity API.
    42 npm
    25
    Apache 2.0

  • evo-scry

    krich11
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP 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