Plan-MCP MCP Server

How to use

You work with an MCP client to send planning, review, and execution requests to Plan-MCP. Start by configuring a connection to the MCP server, then issue tasks such as creating a project plan, reviewing code, or analyzing execution results. The server coordinates Gemini’s planning with Claude’s coding actions and provides iterative feedback to refine outcomes.

How to install

Prerequisites you need before installing Plan-MCP are Python 3.10 or higher, a Google Gemini API key, and Claude Code for MCP integration.

Option A — Quick Start with uvx (recommended)

uvx plan-mcp

# Or add to Claude Code
claude mcp add plan-mcp -- uvx plan-mcp

Option B — Traditional pip installation

pip install plan-mcp

plan-mcp

Configuration and usage notes

Set up your Gemini API key in your environment to enable Gemini access from Plan-MCP.

Example (environment): set the key in your shell or create a .env file with GEMINI_API_KEY and optional GEMINI_MODEL and LOG_LEVEL settings.

MCP connection example (stdio)

{
  "mcpServers": {
    "plan_mcp": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "git+https://github.com/bee4come/plan-mcp.git",
        "plan-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}

Usage with Claude Code

Once configured, you can perform the following common actions through the MCP client integrated in Claude Code: create a project plan, review code, analyze execution, review entire directories, and access files for inline analysis.

For example, to create a plan for a REST API with authentication, instruct the plan_project tool to generate a phased plan with tasks, estimates, and dependencies. To improve code quality, use review_code to get security and performance recommendations, architecture guidance, and best practices.

Common workflows

1) Human asks for a project idea or task. 2) Claude requests a project plan from Plan-MCP. 3) Plan-MCP consults Gemini for a structured plan. 4) Gemini returns a plan, Plan-MCP relays it to Claude. 5) Claude begins implementing tasks. 6) Claude submits code for review. 7) Plan-MCP reviews the code with Gemini and provides improvements. 8) The cycle repeats until the project is complete.

Security and troubleshooting

Ensure your Gemini API key is securely managed and not embedded in code. If you encounter connection issues, verify that the API key is set and that Plan-MCP can reach Gemini services. Check the MCP client logs for errors and confirm that the server process starts without issues.

Development and testing

For development, install in editable mode and run tests to verify functionality. Use standard Python tooling to format and lint code, and run type checks to ensure type safety.

Notes and best practices

Keep your prompts and templates consistent to ensure predictable planning and reviews. Use the interactive elicitation capabilities to tailor plans and reviews to your project’s constraints and preferred tech stack.

plan_project

Create a comprehensive project plan by breaking down requirements into phases and tasks, estimating effort, identifying risks, and considering technical constraints and preferred tech stacks.

review_code

Analyze code quality, detect security issues, suggest performance improvements, and provide design-pattern recommendations with language-agnostic support.

analyze_execution

Debug runtime errors with root cause analysis, provide specific fixes with explanations, verify behavior against expectations, and guide iterative development.

review_directory

Perform a multi-file code quality assessment, offer project structure recommendations, and scan the entire codebase for security issues.