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:

For cost details, see Pricing below.

Pricing

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

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 read, pay-per-usage). x_search bills per tool call — flat, regardless of how many posts Grok reads internally to answer. Concrete comparison:

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

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

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