home / mcp / petamind mcp server

Petamind MCP Server

Provides a multi-candidate patch/test/vision loop to support Claude Code agentic coding workflows.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "alexalexalex222-petamind-mcp": {
      "command": "python",
      "args": [
        "-m",
        "petamind_mcp.mcp_server"
      ]
    }
  }
}

Petamind MCP is a dedicated server that runs a multi-candidate patch, test, and vision loop to support agentic coding workflows. It enables you to orchestrate several model candidates, score them with a vision component, and select a winner to feed into training or downstream tasks.

How to use

You use this MCP server from your Claude Code environment by registering a server configuration that points to thePetamind MCP runtime. You can run the server locally in a Python virtual environment and connect Claude Code to invoke it, or run it in a compatible environment where Python is available.

How to install

Prerequisites you need before installing are a Python runtime and tooling to manage environments, plus access to Claude Code for MCP configuration.

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install the package in editable mode (from source or pip installable package)
pip install -e .

# Or with uv (faster)
uv pip install -e .

# Install Playwright browsers (for vision loop)
playwright install chromium
```} ,{

MCP server configuration for Claude Code

Configure Claude Code to run the MCP server locally. The setup shown uses a Python runtime from your virtual environment and starts the MCP server module as a script.

{
  "mcpServers": [
    {
      "name": "petamind_mcp",
      "type": "stdio",
      "command": "python",
      "args": ["-m", "petamind_mcp.mcp_server"]
    }
  ]
}

Environment and run notes

The server expects a Python environment with its dependencies installed. If you are using a virtual environment, ensure you activate it before starting the MCP server so the command resolves to the correct Python interpreter.

CLI integration steps (quick-start patterns)

Option A (recommended): install from PyPI via pipx and register in Claude Code.

pipx install petamind-mcp
petamind-setup

# Then add to Claude Code (user scope)
claude mcp add-json --scope user petamind-mcp '{"command":"petamind-mcp","args":[]}'

Option B: install from a git clone (for contributors)

From the repository root, run the setup script to install dependencies, then configure Claude Code to point to the MCP server.

./scripts/setup.sh

# Then add the MCP server to Claude Code via .mcp.json or claude mcp add-json

Minimal Claude Code config (user scope)

Use this minimal configuration to connect Claude Code to the local MCP server.

claude mcp add-json --scope user petamind-mcp '{
  "command": "'$(pwd)'/.venv/bin/python",
  "args": ["-m", "petamind_mcp.mcp_server"]
}'

Available tools

petamind_mcp_server

Runs the multi-candidate patch/test/vision loop exposed to Claude Code as an MCP server.

vision_loop

Performs mandatory vision scoring to evaluate candidate outputs.

patch_test_pipeline

Orchestrates the patch/test loop across multiple model candidates.