optuna

The Optuna MCP Server exposes a set of MCP tools built on top of Optuna to automate and analyze hyperparameter optimization tasks. It provides primitives for creating and managing studies, trials, and metrics, plus visualization and dashboard options to inspect optimization progress. Clients can interact with tools such as create_study, set_sampler, ask (to propose new trials), tell (to report results), and various visualization tools to render performance histories, Pareto fronts, and other diagnostics. A Web Dashboard via launch_optuna_dashboard is also available to monitor ongoing optimizations in a browser. You don’t need to memorize Optuna internals; the MCP layer abstracts study management, sampling, and result recording behind simple tool calls, enabling LLM-assisted optimization workflows and interactive analysis through chat interfaces or scripted clients.

Prerequisites:

• Python 3.12 (or 3.13 as indicated by the project).
• An MCP client capable of using uv (Astral uv) or Docker to run MCP servers.

Option A: Install and run via uv

1. Install uv from Astral:

   • Follow the instructions at https://docs.astral.sh/uv/getting-started/installation/

2. Install the Optuna MCP package (Python) if needed for your environment:

   • pip install optuna-mcp

3. Configure your MCP client (e.g., Claude Desktop) to reference the Optuna MCP server: In Claude Desktop, go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json and add:

   { "mcpServers": { "Optuna": { "command": "/path/to/uvx", "args": [ "optuna-mcp" ] } } }

4. Optionally specify storage for persistence by including --storage in the args, for example: { "mcpServers": { "Optuna": { "command": "/path/to/uvx", "args": [ "optuna-mcp", "--storage", "sqlite:///optuna.db" ] } } } )

5. Restart Claude Desktop to apply changes.

Option B: Run via Docker

1. Ensure Docker is installed and running.
2. Use the following MCP config snippet to run the server in a container:

{ "mcpServers": { "Optuna": { "command": "docker", "args": [ "run", "-i", "--rm", "--net=host", "-v", "/PATH/TO/LOCAL/DIRECTORY/WHICH/INCLUDES/DB/FILE:/app/workspace", "optuna/optuna-mcp:latest", "--storage", "sqlite:////app/workspace/optuna.db" ] } } }

5. Access the server as configured by your client. The available tools include Study, Trial, Visualization, and Web Dashboard features.

Tips and common considerations:

• If you enable --storage in UV/docker, Optuna will persist studies and metrics to the specified SQLite database path inside the container or local workspace, so ensure the path is writable.
• The Optuna MCP exposes a suite of tools (Study, Trial, Visualization, Web Dashboard). For multi-objective optimization, use best_trials and Pareto-front related visualizations.
• When using Docker, mounting the workspace directory is important to persist the Optuna database across restarts.
• If you encounter connection issues with your MCP client, verify that the Optuna MCP server is reachable at the configured command/args and that the server process is running.
• For experimentation, you can define multiple studies per storage backend by using different study_name values in the create_study tool.