# grok-quorum-mcp

An [MCP](https://modelcontextprotocol.io/) server that lets **Claude query Grok** as a quorum peer — enabling two AI systems to debate architecture, review code, and reason together before presenting solutions to the user.

## Why a Quorum?

Single-AI workflows have blind spots. When Claude can consult Grok as an equal peer, you get:

- **Stronger code review** — Two AI perspectives catch more bugs than one
- **Better architecture** — Claude proposes, Grok challenges (or vice versa), you decide
- **Live research** — Grok searches the web and X/Twitter in real-time for current information
- **Cost control** — Four modes from cheap quick answers to expensive deep multi-agent analysis

## Privacy & Security

- Runs **100% locally** — no telemetry, no analytics, no data collection
- Your API key never leaves your machine except in direct calls to `api.x.ai`
- Conversation history is in-memory only, cleared when the process exits
- You supply your own xAI API key — we never see it

## Installation

```bash
npm install -g grok-quorum-mcp
```

## API Key Setup

You need an xAI API key. Get one at [console.x.ai](https://console.x.ai).

**Option 1: Environment variable (recommended)**
```bash
export XAI_API_KEY="xai-your-key-here"
```

**Option 2: Key file**
```bash
echo "xai-your-key-here" > ~/.xai_api_key
chmod 600 ~/.xai_api_key
```

> **Security note:** Always use `chmod 600` on the key file. The server will warn you if permissions are too open.

## Configuration

### Claude Code

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

```json
{
  "mcpServers": {
    "grok-quorum": {
      "command": "grok-quorum-mcp",
      "env": {
        "XAI_API_KEY": "xai-your-key-here"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop MCP config:

```json
{
  "mcpServers": {
    "grok-quorum": {
      "command": "npx",
      "args": ["-y", "grok-quorum-mcp"],
      "env": {
        "XAI_API_KEY": "xai-your-key-here"
      }
    }
  }
}
```

## Modes

| Mode | Model | Use Case | Input/Output per 1M | Timeout |
|------|-------|----------|---------------------|---------|
| `fast` | grok-4-1-fast-reasoning | Quick answers, simple questions | $0.20 / $0.50 | 60s |
| `code` | grok-4.20-0309-reasoning | Precise code review with reasoning | $2.00 / $6.00 | 2min |
| `deep` | grok-4.20-multi-agent-0309 | Multi-agent reasoning, architecture | $2.00 / $6.00 | 5min |
| `deep16` | grok-4.20-multi-agent-0309 | Maximum depth multi-agent analysis | $2.00 / $6.00 | 10min |

All models support **2M token context** (2,000,000 tokens input) and 4M TPM rate limits.

**Cost guidance:** `fast` is 10x cheaper than the others. Use it for quick questions. `code`/`deep`/`deep16` all use 4.20-class models at the same per-token rate — the difference is reasoning depth and multi-agent orchestration.

## Tools

| Tool | Description |
|------|-------------|
| `grok_query` | Query Grok with mode selection, optional context, and live search |
| `grok_new_conversation` | Clear conversation history (use when switching topics) |
| `grok_get_history` | View conversation state and approximate token usage |
| `grok_get_last_response` | Recover raw API response — cost protection if parsing fails |

## Usage Examples

**Quick question:**
```
grok_query(message: "What's the best way to handle WebSocket reconnection?", mode: "fast")
```

**Code review with context:**
```
grok_query(
  message: "Review this for security issues and race conditions",
  context: "<file contents here>",
  mode: "code"
)
```

**Architecture debate:**
```
grok_query(
  message: "We're choosing between PostgreSQL and DynamoDB for our event store. Challenge my assumptions.",
  mode: "deep",
  new_conversation: true
)
```

**Live research:**
```
grok_query(
  message: "What are the latest MCP server best practices?",
  mode: "fast",
  search: "web"
)
```

## Advanced Configuration

Override models via environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `XAI_API_KEY` | xAI API key (required) | — |
| `GROK_MODEL_FAST` | Model for fast mode | `grok-4-1-fast-reasoning` |
| `GROK_MODEL_CODE` | Model for code mode | `grok-4.20-0309-reasoning` |
| `GROK_MODEL_DEEP` | Model for deep/deep16 modes | `grok-4.20-multi-agent-0309` |
| `GROK_SYSTEM_PROMPT` | Custom system prompt | (built-in) |

## Troubleshooting

| Issue | Fix |
|-------|-----|
| "No xAI API key found" | Set `XAI_API_KEY` env var or create `~/.xai_api_key` |
| Empty responses | Run `grok_get_last_response` to inspect the raw API payload |
| Timeouts on deep mode | Try `fast` mode first, or simplify the question |
| Model access errors | Check your xAI plan supports the requested model |

## Built by Xega

This project is built and maintained by [Xega.ai](https://xega.ai) — an AI company building intelligent systems that evolve with your essence.

We built this because we believe the best AI workflows involve multiple perspectives. Claude and Grok as equals, with the human as the final decision-maker.

## Contributing

Issues and PRs welcome at [github.com/flycory/grok-quorum-mcp](https://github.com/flycory/grok-quorum-mcp).

## License

MIT — see [LICENSE](LICENSE).