Yellhorn MCP

The server requires the following environment variables:

- GEMINI_API_KEY: Your Gemini API key (required for Gemini models)
- OPENAI_API_KEY: Your OpenAI API key (required for OpenAI models)
- XAI_API_KEY: Your xAI API key (required for Grok models)
- REPO_PATH: Path to your repository (defaults to current directory)
- YELLHORN_MCP_MODEL: Model to use (defaults to "gemini-2.5-pro"). Available options:
- Gemini models: "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite"
- OpenAI models: "gpt-4o", "gpt-4o-mini", "o4-mini", "o3", "gpt-4.1"
- GPT-5 models: "gpt-5", "gpt-5-mini", "gpt-5-nano" (support reasoning mode for gpt-5 and gpt-5-mini)
- xAI Grok models: "grok-4" (256K context) and "grok-4-fast" (2M context)
- Deep Research models: "o3-deep-research", "o4-mini-deep-research"
- Note: Deep Research models (including GPT-5) automatically enable web_search_preview and code_interpreter tools for enhanced research capabilities
- YELLHORN_MCP_REASONING_EFFORT: Set reasoning effort level for GPT-5 models. Options: "low", "medium", "high". This provides enhanced reasoning capabilities at higher cost for supported models (gpt-5, gpt-5-mini). The effort level determines the amount of compute used for reasoning, with higher levels providing more thorough reasoning at increased cost. The server now forwards this value to every GPT-5 request and cost metrics automatically include the appropriate reasoning premium.
- YELLHORN_MCP_SEARCH: Enable/disable Google Search Grounding (defaults to "on" for Gemini models). Options:
- "on" - Search grounding enabled for Gemini models
- "off" - Search grounding disabled for all models

> ℹ️ Grok models now use the official xai-sdk; ensure it is installed in the environment (it is included in the project dependencies, but custom deployments should add it explicitly).

The server also requires the GitHub CLI (gh) to be installed and authenticated.

git clone https://github.com/msnidal/yellhorn-mcp.git
cd yellhorn-mcp

uv sync --group dev

source .venv/bin/activate

uv pip install yellhorn-mcp

Add the server configuration below to your Codex CLI config.toml (~/.config/codex/config.toml by default). Update the GEMINI_API_KEY (or swap in OPENAI_API_KEY/XAI_API_KEY and adjust the model) and REPO_PATH values to match your environment.

[mcp_servers.yellhorn-mcp]
command = "uv"
args = ["run", "yellhorn-mcp"]
env = { "GEMINI_API_KEY" = "your-api-key", "REPO_PATH" = "/path/to/your/repo" }

Restart Codex after updating the configuration so it picks up the new MCP server.

To configure Yellhorn MCP in VSCode or Cursor, create a .vscode/mcp.json file at the root of your workspace with the following content:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gemini-api-key",
      "description": "Gemini API Key"
    }
  ],
  "servers": {
    "yellhorn-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "yellhorn-mcp"],
      "env": {
        "GEMINI_API_KEY": "${input:gemini-api-key}",
        "REPO_PATH": "${workspaceFolder}"
      }
    }
  }
}

To configure Yellhorn MCP with Claude Code directly, add a root-level .mcp.json file in your project with the following content:

{
  "mcpServers": {
    "yellhorn-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "yellhorn-mcp", "--model", "o3"],
      "env": {
        "YELLHORN_MCP_SEARCH": "on"
      }
    }
  }
}

uv sync --group dev