grok-mcp-server

日本語版はこちら

Search X (formerly Twitter) in real-time from your AI assistant — powered by xAI's Grok API.

• No X API account needed — just an xAI API key
• Quick setup — npx with one env var, or deploy to Vercel and connect from claude.ai
• Wide compatibility — Hermes Agent, Claude Code, claude.ai, Cursor, LM Studio, and other MCP clients

MCP Client  ──stdio──▶  grok-mcp-server (npx)  ──API──▶  xAI Grok API
claude.ai   ──OAuth 2.1──▶  grok-mcp-server (Vercel)  ──API──▶  xAI Grok API

What You Can Do

• Search recent posts — Find what people are saying about any topic right now
• Summarize discussions — Get AI-curated summaries of trends, opinions, and reactions
• Extract structured data — Define a JSON Schema to pull exactly what you need (sentiment, topics, key quotes)
• Drill down with follow-ups — Chain searches to filter, compare, or dig deeper into results
• Analyze threads — Pass a post URL to get the original post and top replies ranked by engagement

Quick Start

Option A: Use via npx (Hermes Agent, Claude Code, LM Studio, Cursor, etc.)

No installation required. Add to your MCP client configuration:

{
  "mcpServers": {
    "grok-mcp-server": {
      "command": "npx",
      "args": ["-y", "grok-mcp-server@latest"],
      "env": {
        "XAI_API_KEY": "your-xai-api-key"
      }
    }
  }
}

For Hermes Agent, add the server under mcp_servers in ~/.hermes/config.yaml:

mcp_servers:
  grok-mcp-server:
    command: "npx"
    args: ["-y", "grok-mcp-server@latest"]
    env:
      XAI_API_KEY: "your-xai-api-key"

Restart Hermes after editing the config. The tool will be registered as mcp_grok_mcp_server_x_search.

Get your API key at console.x.ai.

Try it: "Use x_search to find recent posts about MCP servers and summarize the top opinions"

Option B: Deploy to Vercel (claude.ai web / Claude Code)

1. Deploy to Vercel

Click the button above. You'll be prompted to set environment variables — see Environment Variables for what to enter.

After deployment, open your project's root URL to verify the setup. The setup dashboard shows the status of each variable, provides a JWT secret generator, and guides you through any remaining steps.

2. Connect from claude.ai

1. Log in to claude.ai
2. Go to Settings > Integrations > Add More
3. Enter your MCP endpoint URL: https://your-project.vercel.app/api/mcp
4. Click Add — the OAuth authorization flow will start
5. Enter the password you set in AUTHORIZE_PASSWORD and click Allow
6. The x_search tool is now available in your chats!

Once registered on claude.ai, the remote MCP server is also available from Claude Code (CLI / IDE extensions) under the same account.

Try it: "Search X for reactions to the latest Grok release and return JSON with positive and negative themes"

Why grok-mcp-server?

Best for: real-time search, trend analysis, sentiment extraction, topic summarization — any read-only X research workflow.

Not for: posting, retweeting, DMs, follows, or any write operation. Use the official X MCP server (xmcp) for those.

Compared to the official X API / xmcp:

	grok-mcp-server	Official X API (xmcp)
X API account	Not required	Required (pay-per-use credits)
Search results	AI-interpreted summaries & analysis	Raw API data
Structured output	Any JSON Schema	Not built-in
Full archive search	Available (via Grok)	Available (pay-per-use)
Setup	npx + 1 env var, or Vercel deploy	Local server + X Developer app + OAuth callback setup
Write operations	Not supported	Supported

For cost details, see Pricing below.

Pricing

Each x_search call incurs xAI API costs: token fees + X Search tool fee ($0.005/call).

Model	Input	Output
grok-4.20-non-reasoning (default)	$1.25 / 1M tokens	$2.50 / 1M tokens
grok-4.3	$1.25 / 1M tokens	$2.50 / 1M tokens

See xAI Models and Pricing for the latest rates including cached input pricing.

Cost advantage over direct X API

The X API bills per resource ($0.005 per post returned, pay-per-usage). x_search bills per tool call — flat, regardless of how many posts Grok reads internally to answer. Concrete comparison:

Workload	grok-mcp-server	X API direct
Single post + 50-reply thread	~$0.01 (1 tool call + tokens)	~$0.255 (1 request, 51 posts × $0.005)
Trend search returning 100 posts	~$0.01	~$0.50 (1 request, 100 posts × $0.005)

You also get AI-interpreted output — summaries, ranked replies, structured fields per output_schema — instead of raw JSON that you would need to summarize yourself with another LLM call.

Environment Variables

Variable	Required	Description
JWT_SECRET	Yes	JWT signing key (generate via the setup dashboard or openssl rand -base64 32)
XAI_API_KEY	Yes	xAI API key (obtain from console.x.ai)
AUTHORIZE_PASSWORD	Yes	Password for the authorization screen (authorization is blocked if unset)
BASE_URL	No	Public URL override. Auto-detected from Vercel environment variables (VERCEL_PROJECT_PRODUCTION_URL / VERCEL_URL). Defaults to http://localhost:3000 locally.

Local Development

git clone https://github.com/valda/grok-mcp-server.git
cd grok-mcp-server
npm install
cp .env.local.example .env.local  # edit with your values
npm run dev

The dev server starts at http://localhost:3000.

CLI (stdio) development

npm run build:cli        # Build dist/cli.js
npm test                 # Run all tests

Test the stdio server locally:

XAI_API_KEY=your-key node dist/cli.js

Architecture

• OAuth 2.1 — PKCE required, Dynamic Client Registration supported
• MCP — POST-only JSON-RPC endpoint (exposes the x_search tool)
• Stateless — Authorization codes, access tokens, and client registrations are all signed JWTs; Mcp-Session-Id reuses the access token (no separate session JWT)

Endpoints

Path	Method	Description
/	GET	Setup dashboard
/.well-known/oauth-authorization-server	GET	OAuth metadata
/api/oauth/register	POST	Client registration
/api/oauth/authorize	GET/POST	Authorization (consent screen and code issuance)
/api/oauth/token	POST	Token issuance (PKCE verification)
/api/mcp	POST	MCP JSON-RPC endpoint

Tech Stack

• Next.js 16 (App Router)
• jose — JWT signing and verification
• @modelcontextprotocol/sdk — MCP SDK (stdio transport)
• zod — Schema validation
• tsup — CLI bundler
• Vitest — Unit and integration tests
• TypeScript 5

License

MIT