Unleash Your AI Pair Programmer: codemcp - Seamless Code Editing with Claude Desktop

Tired of the copy-paste dance between your LLM and your IDE? codemcp bridges the gap, transforming Claude Desktop into a powerful pair programming assistant. Directly instruct Claude to implement features, fix bugs, and refactor your codebase, with edits applied directly to your files and tests executed automatically. Say goodbye to manual code wrangling and hello to streamlined AI-assisted development!

codemcp carves out a unique niche in the AI coding landscape, offering a compelling alternative to tools like Claude Code, Cursor, Cline, and Aider, by focusing on:

1. Cost-Effective Claude Pro Integration: Leverage Anthropic's affordable $20/month subscription, eliminating exorbitant API bills. Embrace time-based rate limits as a gentle nudge towards thoughtful development.

2. Safe and Controlled Agentic AI: codemcp prioritizes safety by providing a curated set of tools that minimize the risk of misuse by helpful, honest, and harmless LLMs. Git version control is enforced to ensure every code change is reversible. Unleash the power of AI with confidence, reviewing and accepting changes only when you're satisfied.

3. IDE Agnostic Workflow: Focus on the task at hand. codemcp seamlessly integrates with your existing development environment. Instruct Claude, review the changes in your preferred IDE, and iterate with ease.

Getting Started: A Step-by-Step Guide

Before you begin, ensure you have uv and Git installed. On Windows, a reboot after Git installation is often recommended.

Installation via uv (Recommended)

1. Modify your claude_desktop_config.json file:

   {
     "mcpServers": {
       "codemcp": {
         "command": "/Users/<username>/.local/bin/uvx",
         "args": [
           "--from",
           "git+https://github.com/ezyang/codemcp@prod",
           "codemcp"
         ]
       }
     }
   }

   Windows Note: Use double backslashes for paths:

   {
     "mcpServers": {
       "codemcp": {
         "command": "C:\\Users\\<username>\\.local\\bin\\uvx.exe",
         "args": [
           "--from",
           "git+https://github.com/ezyang/codemcp@prod",
           "codemcp"
         ]
       }
     }
   }

2. Restart the Claude Desktop application. A hammer icon will appear, indicating successful MCP loading. Clicking it should reveal "codemcp".

Global Installation with pip (Alternative)

If uv presents challenges, a global pip installation is an option, provided your Python environment meets the requirements (Python 3.12+ and no conflicting dependencies).

1. pip install git+https://github.com/ezyang/codemcp@prod

2. Update claude_desktop_config.json:

   {
       "mcpServers": {
            "codemcp": {
                  "command": "python",
                  "args": ["-m", "codemcp"]
               }
       }
   }

3. Restart Claude Desktop.

   Note: Manual upgrades are required using pip install --upgrade git+https://github.com/ezyang/codemcp@prod.

Essential Tips for Success

• Troubleshooting Logs: Navigate to Settings > Developer > codemcp > Logs to diagnose loading issues. On Windows, logs reside in C:\Users\<user_name>\AppData\Roaming\Claude\logs.

• Git on Windows: If logs report "Git executable not found," reboot your machine after installation. If the issue persists, verify the Git path in System Properties > Environment Variables > System variables > Path.

• Living on the Edge: Replace prod with main for the latest development version. Pin to specific releases (e.g., 0.3.0) for stability.

• uvx in PATH: Specifying only uvx as the command requires it to be in your global PATH.

Unleashing codemcp: A Practical Guide

1. codemcp.toml Configuration: Create a codemcp.toml file in your Git repository checkout. Define commands for formatting and testing:

   format = ["./run_format.sh"]
   test = ["./run_test.sh"]

   Ensure these commands properly configure any necessary virtual environments.

2. Project Initialization: In Claude Desktop, create a Project and add the following to the Project Instructions:

   Initialize codemcp with $PROJECT_DIR
   

   Replace $PROJECT_DIR with the actual path to your project.

3. Engage with Claude: Describe the desired changes to Claude. codemcp will generate a commit for each change.

4. Explore Sample Transcripts:

   • Implement a new feature
   • Fix failing tests
   • Do a refactor

   codemcp will create a commit per chat and amend it as it works on your feature.

Core Philosophy: A Human-in-the-Loop Approach

• Embrace Rate Limits: Use rate limits as opportunities for code review, planning, and collaboration.

• Guided AI, Not Autonomous Agent: codemcp requires active participation. Review changes after each interaction and guide the next steps.

• Time-Conscious Development: When Claude veers off course, it costs time, not money. Monitor incremental output carefully to ensure accuracy.

Advanced Configuration: Tailoring codemcp to Your Needs

Here's a comprehensive overview of codemcp.toml configuration options:

project_prompt = """
Before beginning work on this feature, write a short haiku.  Do this only once.
"""

[commands]
format = ["./run_format.sh"]
test = ["./run_test.sh"]

• project_prompt: A custom prompt loaded when initializing the project.

• commands: Define commands for specific tools. Provide instructions in the project_prompt or use a more verbose syntax:

  [commands.test]
  command = ["./run_test.sh"]
  doc = "Accepts a pytest-style test selector as an argument to run a specific test."

Troubleshooting Deep Dive

• Inspector Mode: Run the server with the inspector using:

  PYTHONPATH=. mcp dev codemcp/__main__.py

• Logging: Logs are written to ~/.codemcp/codemcp.log. Configure the log level in ~/.codemcprc:

  [logger]
  verbosity = "INFO"  # Can be DEBUG, INFO, WARNING, ERROR, or CRITICAL

Contributing: Join the Community

See CONTRIBUTING.md for guidelines on contributing to codemcp.

Type Checking: Ensuring Code Quality

This project utilizes pyright for strict type checking. Key strategies include:

1. Type Stubs:

   • Custom stubs reside in the stubs/ directory.
   • stubPackages in pyproject.toml maps libraries to their stubs.

2. File-Specific Ignores:

   • Used sparingly for complex dynamic typing (primarily in testing code).
   • Configured via tool.pyright.ignoreExtraErrors in pyproject.toml.

Ensure type checking passes by running ./run_typecheck.sh before submitting changes.