# grok-cli-mcp

[![PyPI version](https://badge.fury.io/py/grok-cli-mcp.svg)](https://badge.fury.io/py/grok-cli-mcp)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> MCP server that wraps the Grok CLI, providing seamless access to Grok AI models through the Model Context Protocol.

## What is this?

`grok-cli-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that acts as a bridge between MCP clients (like Claude Code, Cline, Cursor) and the [Grok CLI](https://docs.x.ai/docs). Instead of implementing direct API calls, it leverages the official Grok CLI tool, providing:

- **Three specialized tools**: `grok_query` (general queries), `grok_chat` (multi-turn conversations), `grok_code` (code generation)
- **Simple configuration**: Just install the Grok CLI and set your API key
- **Future-proof**: Automatically benefits from CLI improvements (OAuth, pricing plans, etc.)
- **Minimal maintenance**: No need to track Grok API changes

## Why a CLI Wrapper?

### Benefits

✅ **Leverage existing tooling**: Uses the official Grok CLI, ensuring compatibility and stability

✅ **Future OAuth support**: When Grok CLI adds OAuth authentication, this wrapper will support it automatically without code changes

✅ **Fixed pricing plans**: Can benefit from fixed monthly pricing (like Codex/ChatGPT/Gemini) when Grok introduces CLI-specific plans, rather than paying per API token

✅ **Organization-friendly**: Many organizations prefer audited CLI tools over direct API integrations for security and compliance

✅ **Simpler codebase**: ~400 lines vs 1500+ for a full API client implementation

✅ **Fewer dependencies**: No HTTP client libraries, request/response handling, or complex networking code

✅ **Automatic updates**: CLI bug fixes and new features propagate without code changes

### Tradeoffs

⚠️ **Performance overhead**: Extra process spawning adds ~50-200ms latency per request

⚠️ **CLI dependency**: Requires Grok CLI to be installed and in PATH

⚠️ **Limited control**: Can't access low-level API features not exposed by CLI

⚠️ **Error handling**: CLI error messages may be less structured than API responses

⚠️ **No streaming**: Limited to CLI streaming capabilities (if any)

### When to use this

**Perfect for:**
- Development and prototyping workflows
- Internal tools and automation (<100 req/min)
- Organizations preferring CLI tools over API libraries
- Workflows where convenience matters more than milliseconds
- Teams wanting to benefit from future CLI-specific pricing/features

**Consider direct API for:**
- High-throughput production systems (>1000 req/min)
- Latency-critical applications (<50ms requirements)
- Advanced API features not exposed by CLI
- Streaming response requirements

## Prerequisites

Before installing `grok-cli-mcp`, ensure you have:

1. **Grok CLI**: Install from [X.AI's documentation](https://docs.x.ai/docs)
   ```bash
   # Installation instructions vary by platform
   # See https://docs.x.ai/docs for latest instructions
   ```

2. **Python 3.10+**: Check your version
   ```bash
   python3 --version
   ```

3. **Grok API Key**: Obtain from [X.AI console](https://console.x.ai/)

## Installation

### Option 1: Install from PyPI (Recommended)

```bash
pip install grok-cli-mcp
```

### Option 2: Install with uv

```bash
uv pip install grok-cli-mcp
```

### Option 3: Install with pipx (isolated environment)

```bash
pipx install grok-cli-mcp
```

### Option 4: Install from source

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

### Option 5: Development installation

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

## Quick Start

### 1. Set up your environment

```bash
# Required: Set your Grok API key
export GROK_API_KEY="your-api-key-here"

# Optional: Specify custom Grok CLI path
export GROK_CLI_PATH="/custom/path/to/grok"
```

For permanent setup, add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):

```bash
echo 'export GROK_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
```

### 2. Test the server

```bash
# Run the server directly
python -m grok_cli_mcp

# Or use the command
grok-mcp

# Should start and wait for stdin (Ctrl+C to exit)
```

### 3. Configure for MCP clients

#### For Claude Code

Add to your `.mcp.json`:

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

#### For Cline (VS Code)

Add to `~/.cline/mcp_settings.json`:

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

#### For Cursor

Add to `~/.cursor/mcp.json`:

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

**⚠️ Security Warning**: Never commit API keys to version control. Use environment variables or a secrets manager.

## Usage Examples

### Tool: grok_query

Send a simple prompt to Grok:

```json
{
  "tool": "grok_query",
  "arguments": {
    "prompt": "Explain quantum computing in simple terms",
    "model": "grok-code-fast-1",
    "timeout_s": 120
  }
}
```

**Response**: Plain text answer from Grok

### Tool: grok_chat

Multi-turn conversation with message history:

```json
{
  "tool": "grok_chat",
  "arguments": {
    "messages": [
      {"role": "user", "content": "What is MCP?"},
      {"role": "assistant", "content": "MCP is Model Context Protocol..."},
      {"role": "user", "content": "How does it work?"}
    ],
    "model": "grok-code-fast-1",
    "timeout_s": 120
  }
}
```

**Response**: Grok's answer considering the conversation history

### Tool: grok_code

Code generation with language hints and context:

```json
{
  "tool": "grok_code",
  "arguments": {
    "task": "Create a Python function to parse JSON with error handling",
    "language": "python",
    "context": "Using standard library only, no external dependencies",
    "timeout_s": 180
  }
}
```

**Response**: Complete, usable Python code with explanations

### Advanced: Raw Output Mode

Get structured response with full details:

```json
{
  "tool": "grok_query",
  "arguments": {
    "prompt": "Explain async/await",
    "raw_output": true
  }
}
```

**Response**:
```json
{
  "text": "Async/await is...",
  "messages": [{"role": "assistant", "content": "..."}],
  "raw": "...",
  "model": "grok-code-fast-1"
}
```

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GROK_API_KEY` | **Yes** | - | Your Grok API key from X.AI console |
| `GROK_CLI_PATH` | No | `/opt/homebrew/bin/grok` | Path to Grok CLI binary |

### Model Selection

Available models (as of 2025-12):
- `grok-code-fast-1` - Fast model for code tasks
- `grok-2` - Main model for general tasks
- Other models per [Grok CLI documentation](https://docs.x.ai/docs)

Specify model in each tool call or omit for CLI default.

### Timeout Configuration

Default timeouts by tool:
- `grok_query`: 120 seconds
- `grok_chat`: 120 seconds
- `grok_code`: 180 seconds

Adjust via `timeout_s` parameter for complex tasks.

## Troubleshooting

### "Grok CLI not found"

**Problem**: Server can't locate the Grok CLI binary

**Solutions**:
1. Verify installation:
   ```bash
   which grok
   ```
2. Set explicit path:
   ```bash
   export GROK_CLI_PATH="/path/to/grok"
   ```
3. Add to PATH:
   ```bash
   export PATH="$PATH:/opt/homebrew/bin"
   ```

### "GROK_API_KEY is not set"

**Problem**: API key not in environment

**Solutions**:
1. Export in shell:
   ```bash
   export GROK_API_KEY="xai-..."
   ```
2. Add to shell profile (`.bashrc`, `.zshrc`):
   ```bash
   echo 'export GROK_API_KEY="xai-..."' >> ~/.zshrc
   source ~/.zshrc
   ```
3. Use `.env` file with python-dotenv (see `examples/.env.example`)

### "Grok CLI timed out"

**Problem**: Request took too long

**Solutions**:
1. Increase timeout:
   ```json
   {"timeout_s": 300}
   ```
2. Simplify prompt or break into smaller requests
3. Check network connectivity

### JSON parsing errors

**Problem**: CLI output isn't valid JSON

**Solutions**:
1. Update Grok CLI to latest version:
   ```bash
   # Update instructions vary by installation method
   ```
2. Check for CLI warnings/errors
3. Use `raw_output=true` to see raw CLI response:
   ```json
   {"raw_output": true}
   ```

### Permission errors

**Problem**: Can't execute Grok CLI

**Solutions**:
1. Make CLI executable:
   ```bash
   chmod +x /path/to/grok
   ```
2. Check file ownership and permissions
3. Verify CLI works standalone:
   ```bash
   grok -p "test"
   ```

For more solutions, see [docs/troubleshooting.md](docs/troubleshooting.md).

## Security Best Practices

### Never Commit Secrets

**❌ DO NOT:**
- Commit `.env` files with real API keys
- Include API keys in `.mcp.json` tracked by git
- Share API keys in issues or pull requests
- Hardcode keys in Python files

**✅ DO:**
- Use environment variables: `export GROK_API_KEY="..."`
- Use shell RC files: `~/.bashrc`, `~/.zshrc`
- Use secrets managers in production: AWS Secrets Manager, HashiCorp Vault
- Rotate keys immediately if accidentally exposed

### Obtaining API Keys

1. Visit [X.AI Console](https://console.x.ai/)
2. Sign in with your X.AI account
3. Navigate to API Keys section
4. Generate a new key
5. Store securely (1Password, Bitwarden, etc.)
6. Set as environment variable

### Key Rotation

If you accidentally expose your API key:

1. **Immediately** revoke the key in X.AI console
2. Generate a new key
3. Update environment variables
4. Check git history for exposed keys
5. Consider using tools like `gitleaks` to scan for secrets

### Reporting Security Issues

**Do NOT** open public issues for security vulnerabilities.

Please report security concerns responsibly through GitHub Security Advisories or by contacting the maintainers directly.

## Architecture & Design

This project follows a **CLI wrapper pattern** rather than direct API integration. Key design decisions:

1. **Process isolation**: Each Grok request spawns a subprocess for CLI execution
2. **JSON parsing with fallback**: Attempts structured parsing, falls back to raw output
3. **Context propagation**: Uses FastMCP's Context for logging and progress updates
4. **Async execution**: All operations are async-first for non-blocking behavior

For detailed architecture discussion, see [docs/architecture.md](docs/architecture.md).

## Development

### Running tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage
pytest --cov=grok_cli_mcp --cov-report=html

# Run specific test file
pytest tests/test_utils.py
```

### Code formatting

```bash
# Format code
black .

# Lint code
ruff check --fix .
```

### Type checking

```bash
mypy src/
```

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a 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

**Please ensure**:
- Tests pass (`pytest`)
- Code is formatted (`black`, `ruff`)
- Type hints are correct (`mypy`)
- Documentation is updated

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp) by Jeremiah Lowin
- Uses [Model Context Protocol](https://modelcontextprotocol.io) SDK by Anthropic
- Wraps [Grok CLI](https://docs.x.ai/docs) from X.AI

## Support

- **Documentation**: [README](README.md) • [Architecture](docs/architecture.md) • [Troubleshooting](docs/troubleshooting.md)
- **Issues**: [GitHub Issues](https://github.com/BasisSetVentures/grok-cli-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/BasisSetVentures/grok-cli-mcp/discussions)
- **Grok Documentation**: [docs.x.ai](https://docs.x.ai/docs)

---

**Made by [Basis Set Ventures](https://github.com/BasisSetVentures)** with Claude Code and FastMCP