Bayesian Monte Carlo Tree Search MCP server

This MCP server implements a Monte Carlo Tree Search (MCTS) engine that enables AI assistants like Claude to perform deep, explorative analysis of topics or questions. Using a Bayesian approach, the system systematically explores different angles and interpretations through multiple iterations to produce insightful analyses.

Installation

To install the MCTS MCP server:

1. Clone the repository from GitHub
2. Run the setup script which automates the installation process:

./setup.sh

This script will:

• Install UV (a faster alternative to pip) if not already present
• Create a virtual environment
• Install all required packages
• Create necessary state directories

If you prefer manual setup:

# Install UV
curl -fsSL https://astral.sh/uv/install.sh | bash

# Create and activate virtual environment
uv venv .venv
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

API Key Configuration

The server supports multiple LLM providers including Ollama, OpenAI, Anthropic, and Google Gemini. To configure API keys:

1. Copy the example environment file:

cp .env.example .env

2. Edit the .env file with your API keys:

OPENAI_API_KEY="your_openai_api_key_here"
ANTHROPIC_API_KEY="your_anthropic_api_key_here"
GEMINI_API_KEY="your_google_gemini_api_key_here"

3. Optionally, set default LLM provider and model:

DEFAULT_LLM_PROVIDER="ollama"
DEFAULT_MODEL_NAME="cogito:latest"

Claude Desktop Integration

To integrate with Claude Desktop:

1. Copy the contents of claude_desktop_config.json from the repository
2. Add it to your Claude Desktop configuration (typically at ~/.claude/claude_desktop_config.json)
3. Update the paths in the configuration to match your system
4. Restart Claude Desktop

Example configuration:

{
  "mcpServers": {
    "MCTSServer": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/mcts-mcp-server/src/mcts_mcp_server",
        "server.py"
      ],
      "env": {
        "PYTHONPATH": "/path/to/mcts-mcp-server"
      }
    }
  }
}

Using the MCTS Server

Setting Up the LLM

First, set which LLM provider and model to use:

# List available Ollama models
list_ollama_models()

# Set LLM provider and model
set_active_llm(provider_name="openai", model_name="gpt-4")

# Or use defaults from .env
set_active_llm(provider_name="ollama")

Running an Analysis

To perform an analysis:

1. Initialize the MCTS system:

initialize_mcts(question="Your question here", chat_id="unique_id")

2. Run the MCTS algorithm:

run_mcts(iterations=3, simulations_per_iteration=10)

Note: Running MCTS can take several minutes or even hours depending on the complexity of the question and the number of iterations.

3. Generate a summary of the results:

generate_synthesis()

Analyzing Results

The server provides several tools for analyzing the results:

# List recent MCTS runs
list_mcts_runs()

# Get details about a specific run
get_mcts_run_details('provider_model_timestamp')

# Extract key insights
get_mcts_insights('provider_model_timestamp')

# Generate a comprehensive report
get_mcts_report('provider_model_timestamp', format='markdown')

# Compare multiple runs
compare_mcts_runs(['run_id_1', 'run_id_2'])

Customizing MCTS Parameters

You can customize the MCTS algorithm's behavior:

update_config({
    "exploration_weight": 1.5,
    "use_bayesian_evaluation": True,
    "use_thompson_sampling": True,
    "early_stopping": True
})

Key parameters include:

• exploration_weight: Controls exploration vs. exploitation balance
• use_bayesian_evaluation: Whether to use Bayesian evaluation for node scores
• use_thompson_sampling: Whether to use Thompson sampling for selection
• max_iterations: Number of MCTS iterations to run
• simulations_per_iteration: Number of simulations per iteration

Running the Server Directly

For testing or development:

# Activate virtual environment
source .venv/bin/activate

# Run the server directly
uv run server.py

# OR use MCP CLI tools
uv run -m mcp dev server.py

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "MCTSServer" '{"command":"uv","args":["run","--directory","/home/ty/Repositories/ai_workspace/mcts-mcp-server/src/mcts_mcp_server","server.py"],"env":{"PYTHONPATH":"/home/ty/Repositories/ai_workspace/mcts-mcp-server"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "MCTSServer": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/home/ty/Repositories/ai_workspace/mcts-mcp-server/src/mcts_mcp_server",
                "server.py"
            ],
            "env": {
                "PYTHONPATH": "/home/ty/Repositories/ai_workspace/mcts-mcp-server"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "MCTSServer": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/home/ty/Repositories/ai_workspace/mcts-mcp-server/src/mcts_mcp_server",
                "server.py"
            ],
            "env": {
                "PYTHONPATH": "/home/ty/Repositories/ai_workspace/mcts-mcp-server"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect