evolve-mcp

Universal MCP server for agent self-improvement via evolutionary algorithms.

What is evolve-mcp?

evolve-mcp is an MCP (Model Context Protocol) server that enables autonomous self-improvement for AI agents. It works with Claude Code, Goose, ChatGPT, and any MCP-compatible client.

Agents evolve by:

• Mutating and optimizing prompts using genetic algorithms
• Evaluating fitness through configurable metrics
• Validating safety before deployment
• Tracking performance over time

Inspired by Darwin Gödel Machine and AlphaEvolve, it focuses on openness, modularity, and user control with a local-first design.

Features

• 21 MCP Tools for complete evolution control
• 5 Mutation Strategies: paraphrase, instruction_add, context_expand, cot_injection, tone_shift
• Pluggable Fitness Functions with weighted scoring
• Safety Validation with injection detection
• Metrics Collection with anomaly detection
• Works with any MCP client

Quick Start

Installation

git clone https://github.com/privkeyio/evolve-mcp.git
cd evolve-mcp
uv sync --all-extras

Claude Code

claude mcp add evolve-mcp -- python -m mcp_server.server

Goose

# ~/.config/goose/config.yaml
extensions:
  - name: evolve-mcp
    type: mcp
    command: python -m mcp_server.server

Usage Examples

Start an Evolution Cycle

# Use the start_evolution tool
{
  "trigger_type": "manual",
  "config_overrides": {
    "population_size": 50,
    "max_generations": 10
  }
}

Mutate a Prompt

# Use the mutate_prompt tool
{
  "prompt": "You are a helpful assistant",
  "mutation_type": "instruction_add"
}

Check Safety

# Use the check_safety tool
{
  "text": "Your prompt here",
  "include_policy": true
}

MCP Tools Reference

Evolution Lifecycle (4 tools)

Variant Generation (5 tools)

Fitness Evaluation (5 tools)

Safety Validation (3 tools)

Metrics (4 tools)

Configuration

Environment Variables

Architecture

evolve-mcp/
├── mcp_server/          # MCP integration layer
│   ├── server.py        # FastMCP server with 21 tools
│   ├── state.py         # Cycle state management
│   ├── schemas.py       # Pydantic models
│   ├── serializers.py   # JSON serialization
│   └── errors.py        # Error handling
├── evolution/           # Core evolution engine
│   ├── engine.py        # Genetic algorithm orchestration
│   ├── variants.py      # Mutation & crossover
│   ├── fitness.py       # Fitness evaluation
│   └── interfaces.py    # Abstract interfaces
├── evolve_core/         # Infrastructure
│   ├── safety.py        # Safety validation
│   ├── config.py        # Configuration
│   └── logging_config.py
└── monitoring/          # Metrics collection
    └── metrics.py

Current Status

Production-Ready Components

• Evolution Engine - Full genetic algorithm orchestration with state persistence
• Variant Generator - 5 mutation strategies with deterministic mode
• Fitness Evaluator - Pareto optimization, parallel evaluation
• Metrics Collector - Multi-agent support, anomaly detection
• Safety Validator - Injection detection, policy enforcement
• MCP Server - 21 tools, 6 resources, 3 prompts

Test Coverage

• 173+ tests passing including integration tests
• ~95% coverage for core components

Development

# Install dev dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Format code
uv run black .
uv run isort .

# Type check
uv run mypy evolution monitoring evolve_core mcp_server

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Support

• GitHub Issues: Report bugs or suggest features
• See architecture.md for detailed system design

Citation

@software{evolve-mcp,
  title = {evolve-mcp: Universal MCP Server for Agent Self-Improvement},
  author = {PrivKey LLC},
  year = {2025},
  url = {https://github.com/privkeyio/evolve-mcp}
}