codemcp

When the InitProject tool is called, codemcp performs the following integration steps:

1. Reads the codemcp.toml file from the project root.
2. Constructs a comprehensive system prompt consisting of:
   • Default system instructions.
   • The custom project_prompt defined in the config.
   • Instructions on when and how to use the available tools (e.g., instructing Claude to use the Format tool once a task is complete if a format command is configured).

To use codemcp with Claude Desktop on macOS or Linux, add the server configuration to your ~/.config/anthropic/claude/claude_desktop_config.json file. This method uses uvx to run the package directly from the GitHub repository.

Note: Replace <USERNAME> with your actual system username. Ensure the path to uvx is correct for your installation.

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

To use codemcp with Claude Desktop on Windows, add the server configuration to your %USERPROFILE%\.anthropic\claude\claude_desktop_config.json file. This method uses uvx.exe to run the package directly from the GitHub repository.

Note: Replace <USERNAME> with your actual Windows username.

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

Before starting work, you must create a codemcp.toml file in your Git repository's root directory. This file allows you to define project-specific prompts and permitted commands.

Defining Commands

You must declare commands the agent is allowed to run in the [commands] section. This prevents unrestricted shell access.

• The format command is special: it is automatically executed after every file edit.
• Other commands (like test) are available for the LLM to decide when to use.

Project Prompts

You can define a project_prompt which is loaded when the project is initialized in a chat session.

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"]

To start using codemcp in a Claude chat session, you should provide initialization instructions. It is recommended to create a Claude Project and add the following to the Project Instructions:

Initialize codemcp with $PROJECT_DIR

Replace $PROJECT_DIR with the absolute path to the project directory you want the agent to work on.

If you prefer not to use uv, you can install codemcp globally using pip. This requires Python 3.12 and assumes no dependency conflicts with your global Python environment.

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

2. Configure Claude Desktop: Add the following to your claude_desktop_config.json:

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

3. Update manually: To upgrade, run: pip install --upgrade git+https://github.com/ezyang/codemcp@prod

For more control, you can provide specific documentation for individual tools within the [commands] section. This helps the LLM understand how to use the command correctly.

Use the [commands.<tool_name>] syntax to provide a doc string alongside the command array.

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

Use the project_prompt key in codemcp.toml to provide Claude with project-specific instructions, context, or coding standards. This string is automatically injected into the system prompt during project initialization.

project_prompt = """
Project-specific instructions for Claude go here.
"""

The [commands] section allows you to define shell commands that Claude can execute through specific tools. Commands are defined as arrays of strings; these strings are joined with spaces and executed in a shell context.

Currently, the format command is supported. It is used by the Format tool to apply project-specific code formatting standards.

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