Grok

You run a lightweight MCP server that bridges MCP clients to the Grok CLI, giving you access to Grok AI models through a stable, future-proof wrapper. It handles tool calls for general queries, chats, and code generation by invoking the official Grok CLI, so you can prototype, automate, and integrate Grok model capabilities with familiar MCP workflows.

How to use

You start the Grok MCP server locally and connect MCP clients to it using a stdio configuration. The server exposes three tools you can call from your MCP client: grok_query for general prompts, grok_chat for multi-turn conversations, and grok_code for code generation. Provide your Grok API key as an environment variable when running the server, and your client will send requests through the MCP protocol as if you were talking to a hosted model.

How to install

Prerequisites you need before installing the server:

Grok CLI must be installed and in your PATH.

Python 3.10+ must be available on your system.

You also need a Grok API key from the X.AI console.

Install from PyPI (Recommended)

pip install grok-cli-mcp

Install with uv

uv pip install grok-cli-mcp

Install with pipx (isolated environment)

pipx install grok-cli-mcp

Install from source

git clone https://github.com/BasisSetVentures/grok-cli-mcp.git
cd grok-cli-mcp
pip install -e .

Development installation

git clone https://github.com/BasisSetVentures/grok-cli-mcp.git
cd grok-cli-mcp
pip install -e ".[dev]"

Run the server to start using it

python -m grok_cli_mcp

Or run the executable if you have a wrapper installed:

grok-mcp

Configure for MCP clients

Use the following stdio configuration to expose the server to MCP clients. This runs the Grok MCP server locally via Python and provides the required API key through an environment variable.

{
  "mcpServers": {
    "grok": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "grok_cli_mcp"],
      "env": {
        "GROK_API_KEY": "your-api-key-here"
      }
    }
  }
}

Environment variables

Set the Grok API key in the environment before starting the server.

export GROK_API_KEY="your-api-key-here"

Optional, if you need to point to a custom Grok CLI binary path:

export GROK_CLI_PATH="/custom/path/to/grok"

## Notes on usage

Security best practices: never commit API keys in code or configuration files. Use environment variables or secret managers in production. Ensure the Grok CLI is kept up to date to benefit from new features and fixes.

## Troubleshooting

If you encounter issues starting the server, verify the Grok CLI is installed and accessible, and that the GROK\_API\_KEY is set in the environment.

## Tools available

The server provides three MCP tools that map to Grok CLI functionality: `grok_query` for single-turn prompts, `grok_chat` for multi-turn conversations, and `grok_code` for code generation. Each tool forwards the request to the Grok CLI and returns the resulting text or code.

## Available tools

### grok\_query

Query Grok with a prompt and receive a plain text response. Useful for general questions and simple tasks.

### grok\_chat

Interact with Grok in a multi-turn conversation, providing a history of messages and receiving responses that consider prior context.

### grok\_code

Generate code based on a task, with language hints and context, returning usable code along with explanations.