Agent Genesis MCP Server

MCP server for searching Claude Code conversation history

This package provides an MCP (Model Context Protocol) server that enables Claude Code to search through your conversation history using the Agent Genesis API.

Current package version: 1.6.0

Prerequisites

• Python 3.10+
• Agent Genesis API running (via Docker)

Installation

From PyPI

pip install agent-genesis-mcp

From Source

git clone https://github.com/agentgenesis/agent-genesis.git
cd agent-genesis/mcp-server
pip install -e .

Configuration

Add to your Claude Code configuration:

Linux/macOS: ~/.claude.json Windows: %USERPROFILE%\.claude.json

{
  "mcpServers": {
    "agent-genesis": {
      "command": "agent-genesis-mcp",
      "args": []
    }
  }
}

Or if installed in a virtual environment:

{
  "mcpServers": {
    "agent-genesis": {
      "command": "/path/to/venv/bin/agent-genesis-mcp",
      "args": []
    }
  }
}

Available Tools

search_conversations

Search through your Claude Code conversation history.

Parameters:

• query (str): Search query string
• limit (int, optional): Max results (default: 5, max: 50)
• project (str, optional): Filter by project name

Example:

search_conversations(query="authentication flow", limit=10, project="my-app")

Returns:

{
  "success": true,
  "results": [
    {
      "score": 0.856,
      "project": "my-app",
      "timestamp": "2025-01-15T10:30:00Z",
      "conversation_id": "conv_abc123",
      "content_snippet": "Implementing authentication...",
      "full_content_length": 1245
    }
  ],
  "total_found": 3,
  "query": "authentication flow"
}

get_api_stats

Get statistics about the indexed conversation corpus.

Returns:

• Total conversations indexed
• Number of unique projects
• Index health status

check_api_health

Verify that the Agent Genesis API is running and healthy.

manage_scheduler

Control automatic conversation indexing.

Parameters:

• action (str): One of status, enable, disable, remove, configure
• frequency_minutes (int, optional): Indexing interval (default: 30)

Examples:

# Check status
manage_scheduler(action="status")

# Enable with 1-hour interval
manage_scheduler(action="enable", frequency_minutes=60)

# Disable
manage_scheduler(action="disable")

index_conversations

Manually trigger conversation indexing.

Parameters:

• full_reindex (bool): Reindex all conversations (default: False)
• time_range (str, optional): Time filter - "1h", "24h", "7d", "30d"
• force (bool): Bypass rate limiting (default: False)

Examples:

# Index new conversations only
index_conversations()

# Full reindex
index_conversations(full_reindex=True, force=True)

# Index last 24 hours
index_conversations(time_range="24h")

Available Resources

• config://api-endpoints - API endpoint documentation
• agentgenesis://stats - Current corpus statistics
• agentgenesis://health - Current API health status

Available Prompts

• search_conversations_workflow - Guided workflow for building and refining searches
• trigger_indexing_workflow - Guided workflow for manual indexing and scheduler operations

API Configuration

By default, the MCP server connects to http://localhost:8080.

To use a different endpoint, set the environment variable:

export AGENT_GENESIS_API_URL=http://your-host:port

Resources

The server provides MCP resources for documentation:

• config://api-endpoints - API endpoint documentation
• agentgenesis://stats - Current corpus statistics
• agentgenesis://health - API health status

Troubleshooting

"API Connection Failed"

Ensure the Agent Genesis Docker container is running:

docker-compose ps
curl http://localhost:8080/health

"Timeout" errors

The API might be busy indexing. Try again in a few seconds.

Tool not found in Claude

1. Verify the MCP server is in your config file
2. Restart Claude Code / Claude Desktop
3. Check MCP logs (View → Developer → MCP Logs)

Development

# Clone the repo
git clone https://github.com/agentgenesis/agent-genesis.git
cd agent-genesis/mcp-server

# Install dev dependencies
pip install -e ".[dev]"

# Validate MCP compliance
python3 test_mcp_2025_compliance.py

# Run the interactive MCP smoke test
python3 test_mcp.py

# Format code
black .
ruff check .

License

MIT License - see LICENSE for details.