Yellhorn MCP

What is Yellhorn MCP?

Yellhorn MCP is a Model Context Protocol server that creates detailed workplans for implementing tasks or features. It uses large AI models (e.g., Gemini 2.5 Pro, GPT‑5, o3, Grok‑4) with full codebase context, URL access, and optional web search. The server is designed for coding agents like Claude Code to define work, and later to review the output against the original requirements.

How to use Yellhorn MCP?

Install via uv sync --group dev or uv pip install yellhorn-mcp. Set environment variables GEMINI_API_KEY, OPENAI_API_KEY, XAI_API_KEY, REPO_PATH, and optionally YELLHORN_MCP_MODEL and YELLHORN_MCP_SEARCH. The GitHub CLI (gh) must be installed and authenticated. Configure the server in your MCP client (Codex CLI, VSCode/Cursor, or Claude Code) using a config.toml or mcp.json file with command uv run yellhorn-mcp.

Key features of Yellhorn MCP

• Creates detailed workplans posted as GitHub issues
• Judges code diffs against the original workplan
• Seamless GitHub integration with labeled issues and sub‑issues
• .yellhornignore file to exclude files from AI context
• MCP resources for listing and retrieving workplans
• Google Search Grounding enabled by default for Gemini models

Use cases of Yellhorn MCP

• Defining implementation tasks for coding agents (e.g., Claude Code)
• Reviewing code agent output against specified requirements
• Generating workplans with full codebase awareness
• Iteratively revising workplans based on feedback

FAQ from Yellhorn MCP

What models does Yellhorn MCP support?

It supports Gemini (2.5‑pro, 2.5‑flash, 2.5‑flash‑lite), OpenAI (GPT‑4o, GPT‑4o‑mini, o4‑mini, o3, GPT‑4.1, GPT‑5 series), and xAI Grok (Grok‑4, Grok‑4 Fast) models. Deep Research models (o3‑deep‑research, o4‑mini‑deep‑research, GPT‑5) enable web search and code interpreter tools.

How do I exclude files from AI context?

Create a .yellhornignore file in your repository, similar to .gitignore. The server also provides the curate_context tool to generate a .yellhorncontext whitelist that further reduces token usage.

What are the prerequisites for using Yellhorn MCP?

You need API keys for the models you plan to use (Gemini, OpenAI, or xAI), the GitHub CLI (gh) installed and authenticated, and a Python environment managed by uv. The repository to analyze must be accessible via REPO_PATH.

Can I disable web search in workplans?

Yes. Set the environment variable YELLHORN_MCP_SEARCH to "off" (default is "on" for Gemini models). You can also pass disable_search_grounding: true to individual tool calls.

How does workplan judgment work?

The judge_workplan tool compares two git refs (base and head) against a workplan stored in a GitHub issue. It creates a sub‑issue, then asynchronously evaluates the diff with full codebase context and posts detailed feedback.