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)
| Tool | Description |
|---|---|
start_evolution |
Begin an evolution cycle |
get_evolution_status |
Check cycle progress |
cancel_evolution |
Stop a running cycle |
resume_evolution |
Resume from checkpoint |
Variant Generation (5 tools)
| Tool | Description |
|---|---|
generate_population |
Create variant population |
mutate_prompt |
Apply specific mutation |
crossover_variants |
Combine two variants |
generate_ab_pair |
Create A/B test pair |
analyze_prompt |
Get complexity metrics |
Fitness Evaluation (5 tools)
| Tool | Description |
|---|---|
evaluate_variant |
Calculate fitness score |
explain_fitness |
Detailed breakdown |
register_fitness_function |
Add custom metric |
update_fitness_weights |
Adjust weights |
list_fitness_functions |
List available |
Safety Validation (3 tools)
| Tool | Description |
|---|---|
validate_variant |
Full safety check |
check_safety |
Quick text check |
add_safety_pattern |
Add custom pattern |
Metrics (4 tools)
| Tool | Description |
|---|---|
record_metrics |
Log performance data |
get_metrics_window |
Aggregated metrics |
check_evolution_trigger |
Should evolve? |
detect_anomalies |
Find anomalies |
Configuration
Environment Variables
| Variable | Default | Description |
|---|---|---|
EVOLVE_MCP_POPULATION_SIZE |
50 |
Default population size |
EVOLVE_MCP_MAX_GENERATIONS |
10 |
Default max generations |
EVOLVE_MCP_FITNESS_THRESHOLD |
0.95 |
Early stop threshold |
EVOLVE_MCP_MAX_CONCURRENT_CYCLES |
1 |
Parallel evolution limit |
EVOLVE_MCP_CHECKPOINT_DIR |
.evolve-mcp/checkpoints |
State storage |
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
AGPL-3.0 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}
}
Metadata
Release files for iflow-mcp_privkeyio-evolve-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_privkeyio_evolve_mcp-0.1.0.tar.gz | 73.7 kB | Without provenance | Details for iflow_mcp_privkeyio_evolve_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_privkeyio_evolve_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_privkeyio_evolve_mcp-0.1.0-py3-none-any.whl |
Total release size: 151.8 kB
Release files / iflow_mcp_privkeyio_evolve_mcp-0.1.0.tar.gz
| Download URL | iflow_mcp_privkeyio_evolve_mcp-0.1.0.tar.gz |
|---|---|
| Size | 73.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1c18468beb0b8ca015f131316ff03eda03fe8449d7144b78585b16727d1b076f
|
|
BLAKE2b-256 checksum How to use checksums |
63ea57cb6696583ff0cd6337a9b5292dd049dac6e0970a46bace274cd12dd7c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_privkeyio_evolve_mcp-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_privkeyio_evolve_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 78.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7e32cf5b95e5aecced82bf0d59a86e7049ec2f9bb0e31f2dec1a3c4f2f08f3de
|
|
BLAKE2b-256 checksum How to use checksums |
dd630ff35f3bef556535ebb1153c67a29a3eea9c9cf5f7aa93cb23b4a2668ff6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_privkeyio-evolve-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.