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

🚀 Features

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

✅ Complete MCP Feature Matrix

Feature	Status	Description
Resources	✅	File system access (file://, dir://, workspace://)
Prompts	✅	4 structured prompt templates for common tasks
Tools	✅	10 comprehensive tools for project management
Discovery	✅	Dynamic tool discovery (handled by FastMCP)
Sampling	✅	LLM text generation for documentation and tests
Roots	✅	Workspace navigation and project root suggestions
Elicitation	✅	Interactive user input collection

🔧 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

Human → Claude: "Help me build a web scraper"
Claude → Plan-MCP: Requests project plan
Plan-MCP → Gemini: Analyzes requirements
Gemini → Plan-MCP: Returns structured plan
Plan-MCP → Claude: Delivers plan
Claude: Implements first task
Claude → Plan-MCP: Submits code for review
Plan-MCP → Gemini: Reviews code
Gemini → Plan-MCP: Provides feedback
Plan-MCP → Claude: Delivers improvements
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

"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
Connection errors
- Verify your internet connection
- Check if the Gemini API is accessible
- Ensure your API key has proper permissions
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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

An MCP server that uses Google Gemini AI to analyze requirements, create project plans, review code quality, and provide execution analysis feedback for software development projects.

Related MCP Servers

Gemini Thinking Server
bartekke8it56w2
A
security
F
license
A
quality
An MCP server implementation that leverages Google's Gemini API to provide analytical problem-solving capabilities through sequential thinking steps without code generation.
Last updated -
1
18
JavaScript
MCP Gemini API Server
techkwon
A
security
F
license
A
quality
A server that provides access to Google Gemini AI capabilities including text generation, image analysis, YouTube video analysis, and web search functionality through the MCP protocol.
Last updated -
6
18
3
TypeScript
MCP Gemini Server
bsmi021
A
security
A
license
A
quality
A dedicated server that wraps Google's Gemini AI models in a Model Context Protocol (MCP) interface, allowing other LLMs and MCP-compatible systems to access Gemini's capabilities like content generation, function calling, chat, and file handling through standardized tools.
Last updated -
16
29
TypeScript
MIT License
MCP Gemini Server
Novakiki
-
security
A
license
-
quality
An MCP server that enables other AI models (like Claude) to use Google's Gemini models as tools for specific tasks through a standardized interface.
Last updated -
1
TypeScript
MIT License

View all related MCP servers