Skip to main content
Glama
guzus

Grok MCP Server

by guzus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Grok MCP Server

Search X.com in real-time with xAI's Grok API - directly from Claude

PyPI version Python 3.12+ License: MIT MCP

A Model Context Protocol server that brings real-time X/Twitter search to Claude. Powered by xAI's Live Search API, it provides instant access to posts, users, threads, and trending topics.

Why Grok MCP?

  • Real-time data - Access live X.com content, not cached or outdated information

  • Native Claude integration - Works seamlessly with Claude Desktop and Claude Code

  • Simple setup - One command to install, one config to add

  • Open source - MIT licensed, community-driven

Related MCP server: grok-mcp-server

Quick Start

1. Get an xAI API Key

Get your API key from console.x.ai

2. Install

uvx grok-mcp

3. Configure Claude

For Claude Code - Add to .mcp.json in your project:

{
  "mcpServers": {
    "grok": {
      "command": "uvx",
      "args": ["grok-mcp"],
      "env": {
        "XAI_API_KEY": "your-api-key"
      }
    }
  }
}

For Claude Desktop - Add to your config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "grok": {
      "command": "uvx",
      "args": ["grok-mcp"],
      "env": {
        "XAI_API_KEY": "your-api-key"
      }
    }
  }
}

4. Use It

Ask Claude things like:

  • "Search X for posts about AI"

  • "What's trending on X right now?"

  • "Find tweets from @elonmusk about Tesla"

Available Tools

Tool

Description

search_posts

Search posts with filters (handles, date range, analysis mode)

search_users

Find user profiles

search_threads

Discover conversation threads

get_trends

Get trending topics by location

health_check

Verify API connection

Examples

Search Posts

Search X for posts about "AI safety" from the last week

Filter by User

Find recent posts from @anthropic about Claude

Get Trends

What are the trending topics in tech right now?

Development

# Clone
git clone https://github.com/guzus/grok-mcp.git
cd grok-mcp

# Install dependencies
uv sync --dev

# Run tests
uv run pytest

# Run locally
XAI_API_KEY=your-key uv run python -m grok_mcp

Architecture

src/grok_mcp/
├── server.py           # MCP server implementation
├── grok_client.py      # xAI Live Search API client
├── search_tools.py     # Tool implementations
├── response_formatter.py
├── config.py
└── exceptions.py

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

License

MIT License - see LICENSE for details.

Links

Built with xAI Grok and Model Context Protocol

Available Tools

5 tools
health_checkA

Check the health and status of the Grok API connection

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden. It only states the action (check health) but does not disclose what a healthy status means, the output format, or whether it has side effects. For a read-only health check, more detail on what constitutes a successful check would be helpful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that is appropriately sized and front-loaded. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, no output schema, and is a simple health check, the description is complete enough. It covers the essential purpose without missing critical context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, and the schema coverage is trivial 100%. The description does not add meaning beyond the schema, but baseline is 4 due to no parameters requiring elaboration.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks the health and status of the Grok API connection, which is a specific verb+resource. It effectively distinguishes from sibling tools like get_trends or search_posts, which focus on data retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used to verify connection health before other operations, but it provides no explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_postsB

Search X.com posts with advanced filtering and analysis options

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query for X.com posts
max_resultsNoMaximum number of results to return (1-100)
handlesNoFilter by specific user handles (without @)
start_dateNoStart date for search (YYYY-MM-DD format)
end_dateNoEnd date for search (YYYY-MM-DD format)
analysis_modeNoAnalysis depth: basic for quick results, comprehensive for detailed analysisbasic

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; the description only mentions 'advanced filtering and analysis options' without disclosing behavioral traits such as authentication, rate limits, pagination, or whether operations are read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence but lacks structure. It is concise but could be better organized, e.g., by distinguishing between filtering and analysis.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description should explain return values or behavior. It only mentions 'advanced filtering and analysis' without detailing output or analysis depth implications.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and parameters are well-described in the schema. The description adds no additional meaning beyond the schema, meeting baseline expectations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the verb 'Search' and the resource 'X.com posts', and distinguishes from sibling tools like search_threads and search_users by focusing on posts rather than threads or users.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives (e.g., search_threads, search_users) or when to choose analysis_mode values. Missing prerequisites, context, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_threadsB

Search X.com conversation threads and replies

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query for conversation threads
max_resultsNoMaximum number of threads to return (1-20)

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It only states 'Search X.com conversation threads and replies' without mentioning rate limits, authentication needs, pagination, or result format. This is insufficient for an agent to understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (5 words), but it lacks critical information about usage and behavior. Conciseness is positive, but under-specification reduces its value. Not every needed piece of information is included.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is incomplete given the presence of sibling tools (search_posts, search_users) that could overlap. No output schema exists, yet the description does not explain return values or thread structure. The tool has only 2 parameters, so the description could easily be more helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (both parameters have descriptions). The tool description adds no further meaning beyond the schema, hence baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Search' and the resource 'X.com conversation threads', distinguishing it from sibling tools like search_posts and search_users which search different entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives such as search_posts or search_users. The description does not mention when to avoid using it or provide any decision framework.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_usersC

Search for X.com users and profiles

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query for X.com users
max_resultsNoMaximum number of results to return (1-50)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description should disclose behavioral traits like rate limits or authentication needs. It only states the basic action, missing important context about how the search behaves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, clear sentence that is front-loaded and free of fluff. It could be expanded with more detail, but as a concise statement it achieves its goal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and low complexity, the description is adequate but minimal. It lacks behavioral and usage context that would help an agent fully understand the tool's capabilities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with clear descriptions for both params (query and max_results). The description does not add extra meaning, but the schema already handles parameter semantics adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: searching for X.com users and profiles. It is specific enough to distinguish from siblings like search_posts and search_threads, though it could be more precise (e.g., by name or handle).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., search_posts) is provided. The description implies usage for user search but lacks explicit context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 5 tool updatesv0.2.1
    • First observedget_trends
    • First observedhealth_check
    • First observedsearch_posts
    • First observedsearch_threads
    • First observedsearch_users
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.6/5.0

Scored across 5 tools

Disambiguation5/5

Each tool targets a distinct aspect: trends, health, posts, threads, and users. There is no overlap in functionality.

Naming Consistency5/5

All tools follow a consistent verb_noun snake_case pattern (e.g., get_trends, search_posts). health_check is the only deviation but still aligns with common convention.

Tool Count5/5

5 tools is well-scoped for a server focused on X.com search and trends. It covers core functionalities without being overwhelming or too sparse.

Completeness4/5

The tool set covers trending topics, search across posts/threads/users, and API health. Missing direct access to specific posts or user profiles beyond search, but the main use cases are addressed.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Twitter MCP Server

    GenAIwithMS
    A
    license
    A
    quality
    A
    maintenance
    Enables seamless interaction with Twitter/X platform through Claude AI, allowing users to post tweets with images, search for tweets, and engage in conversations using natural language commands.
    10
    32 npm
    25
    MIT

  • x-search-mcp

    toocheap
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables real-time search of X (Twitter) posts, user timelines, and trends using either xAI's Responses API or the official X API v2.
    4
    -

  • grok-mcp

    Pantainos-Toolkit
    F
    license
    A
    quality
    C
    maintenance
    Enables searching X (Twitter) using the xAI Grok API to get summarised answers with citations. Supports filtering by handles, date range, and image/video understanding.
    1
    2
    -

Appeared in Searches