Plan-MCP

A Model Context Protocol (MCP) server that leverages Google Gemini AI for intelligent project planning and code review.

🌟 Overview

Plan-MCP acts as an AI-powered project architect that bridges Gemini's planning capabilities with Claude's coding abilities:

• Gemini as Architect: Analyzes requirements, creates project plans, reviews code quality

• Claude as Developer: Implements code based on Gemini's guidance

• Continuous Feedback Loop: Gemini reviews execution results and provides iterative improvements

Related MCP server: Gemini MCP Server

🚀 Features

Plan-MCP provides complete MCP feature support, making it one of the most comprehensive MCP servers available:

✅ Complete MCP Feature Matrix

🔧 Core Tools

1. Project Planning (plan_project)

• Break down complex requirements into structured phases and tasks

• Generate detailed project plans with priorities and dependencies

• Estimate effort and identify potential risks

• Support for technical constraints and preferred tech stacks

2. Code Review (review_code)

• Comprehensive code quality analysis

• Security vulnerability detection

• Performance optimization suggestions

• Best practices and design pattern recommendations

• Language-agnostic support

3. Execution Analysis (analyze_execution)

• Debug runtime errors with root cause analysis

• Provide specific code fixes with explanations

• Evaluate if execution meets expected behavior

• Guide iterative development with next steps

4. Directory Review (review_directory)

• Complete project/directory analysis

• Multi-file code quality assessment

• Project structure recommendations

• Security scanning across entire codebase

🎯 Advanced Features

Interactive Tools (Elicitation)

• Interactive Project Planning: Collects user preferences and requirements dynamically

• Interactive Code Review: Customizes review focus based on user needs

LLM Sampling

• Documentation Generation: Auto-generates comprehensive docs for code

• Test Generation: Creates unit tests with proper assertions and edge cases

File System Resources

• File Access: Read individual files with file:// URIs

• Directory Access: Access entire directories with dir:// URIs

• Workspace Navigation: Current workspace info with workspace://current

Workspace Management (Roots)

• Workspace Roots: Lists available workspace directories

• Project Suggestions: Recommends appropriate project locations by type

Prompt Templates

• Code Review Template: Structured code review prompts

• Project Planning Template: Interactive planning conversations

• Debug Assistant: Systematic debugging guidance

• Architecture Review: System architecture analysis

📋 Prerequisites

• Python 3.10 or higher

• Google Gemini API key

• Claude Code (for MCP integration)

🛠️ Installation

Quick Start with uvx (Recommended)

# Install and run directly with uvx
uvx plan-mcp

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

Traditional pip Installation

# Install from PyPI
pip install plan-mcp

# Run the server
plan-mcp

🔧 Configuration

Set up your Gemini API key

export GEMINI_API_KEY="your_gemini_api_key_here"

Or create a .env file:

GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-1.5-pro
LOG_LEVEL=INFO

Claude Code Integration

🚀 Method 1: Direct from GitHub (Recommended)

Run directly from GitHub using uv without local installation:

# Team/project configuration (recommended)
claude mcp add -s project plan-mcp -- uv tool run --from git+https://github.com/bee4come/plan-mcp.git plan-mcp

This creates a .mcp.json file in your project root. For secure API key management, edit the file:

🔧 Method 2: Local Installation (Recommended)

Install locally for reliable connection:

# Clone and install dependencies
git clone https://github.com/bee4come/plan-mcp.git
cd plan-mcp
pip install mcp google-generativeai python-dotenv pydantic loguru rich

# Add to Claude Code  
claude mcp add -s project plan-mcp -- python run_mcp.py

✅ Verify Installation

Check if the MCP server is working:

# List MCP servers
claude mcp list

# Check server details  
claude mcp get plan-mcp

# Test in Claude Code by typing: /mcp

{
  "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}"
      }
    }
  }
}

Alternative Configuration Options

Personal global configuration:

claude mcp add -s user plan-mcp -e GEMINI_API_KEY=your_api_key -- uv tool run --from git+https://github.com/bee4come/plan-mcp.git plan-mcp

Local testing configuration:

claude mcp add plan-mcp -e GEMINI_API_KEY=your_api_key -- uv tool run --from git+https://github.com/bee4come/plan-mcp.git plan-mcp

Managing MCP Services

# List all services
claude mcp list

# Get service details
claude mcp get plan-mcp

# Check status in Claude Code
# Type /mcp command to view connection status

💻 Usage

Once configured, you can use these tools in Claude Code:

1. Create a project plan

Use the plan_project tool to create a plan for building a REST API for task management with user authentication

2. Review code

Use the review_code tool to review this Python function for security and performance issues: [paste code]

3. Review entire directory/project

Use the review_directory tool to review my entire Python project at /path/to/project for security and code quality issues

4. Analyze execution errors

Use the analyze_execution tool to help me debug this error: [paste code and error]

5. Access files and directories

You can now ask Claude to analyze files directly:
"Please review the code in file:///path/to/my/project and suggest improvements"

🏗️ Architecture

plan-mcp/
├── plan_mcp/
│   ├── api/              # Gemini API integration
│   ├── tools/            # MCP tools (planner, reviewer, analyzer)
│   ├── prompts/          # System prompts for Gemini
│   ├── utils/            # Utilities (logging, etc.)
│   ├── config.py         # Configuration management
│   ├── models.py         # Pydantic data models
│   └── server.py         # MCP server implementation
└── README.md

🤝 Workflow Example

1. Human → Claude: "Help me build a web scraper"

2. Claude → Plan-MCP: Requests project plan

3. Plan-MCP → Gemini: Analyzes requirements

4. Gemini → Plan-MCP: Returns structured plan

5. Plan-MCP → Claude: Delivers plan

6. Claude: Implements first task

7. Claude → Plan-MCP: Submits code for review

8. Plan-MCP → Gemini: Reviews code

9. Gemini → Plan-MCP: Provides feedback

10. Plan-MCP → Claude: Delivers improvements

11. Cycle continues...

📚 API Reference

Tools

plan_project

• Description: Create a comprehensive project plan

• Parameters:

  • description (required): Project description

  • requirements: List of specific requirements

  • constraints: Project constraints

  • tech_stack: Preferred technologies

review_code

• Description: Review code for quality and issues

• Parameters:

  • code (required): Code to review

  • language (required): Programming language

  • context: Additional context

  • focus_areas: Specific areas to focus on

analyze_execution

• Description: Analyze execution results and debug errors

• Parameters:

  • code (required): Code that was executed

  • execution_output (required): Output or error messages

  • expected_behavior: What the code should do

  • error_messages: Specific error messages

  • language: Programming language (default: python)

🧪 Development

Set up development environment

# Clone the repository
git clone https://github.com/bee4come/plan-mcp.git
cd plan-mcp

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

Code quality

# Format code
black plan_mcp/

# Lint code
ruff check plan_mcp/

# Type checking
mypy plan_mcp/

🐛 Troubleshooting

Common Issues

1. "GEMINI_API_KEY not found"

   • Ensure your API key is set in environment variables: export GEMINI_API_KEY="your_key_here"

   • Or create a .env file in your working directory with GEMINI_API_KEY=your_key_here

   • Get your API key from: https://makersuite.google.com/app/apikey

2. Connection errors

   • Verify your internet connection

   • Check if the Gemini API is accessible

   • Ensure your API key has proper permissions

3. MCP connection issues

   • Restart Claude Code after configuration

   • Check that the server starts without errors

   • Look at Claude Code logs for errors

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Google Gemini for powerful AI capabilities

• Anthropic for Claude and the MCP protocol

• The open-source community for inspiration