Optuna MCP

What optuna/optuna-mcp MCP server does

The optuna/optuna-mcp MCP server makes core Optuna operations available as MCP tools. It can create or load studies by name, configure optimization directions, choose a sampler, and manage metric labels. Agents can list studies, retrieve trial data as CSV, inspect the best trial, or query the Pareto front for multi-objective studies.

The server also supports the trial loop. ask receives a search-space dictionary and returns suggested parameters, while tell records one trial's objective value or values. Trial-level user attributes can be written and read using a trial number, key, and value. This makes it possible to attach metadata to individual optimization attempts.

How it works

An MCP client calls the exposed tools and supplies the study, trial, search-space, or plotting arguments. Study creation accepts a name and optional minimize or maximize directions. Multi-objective studies can define multiple metric names and objective directions. The server uses Optuna to produce suggestions and evaluate the resulting study state when the client requests trial or analysis data.

Visualization tools return images for optimization history, hypervolume history, Pareto fronts, contours, parallel coordinates, slices, parameter importances, empirical distribution functions, timelines, and ranks. Several plots accept an objective index, objective name, or selected parameter list. Pareto-front plotting can optionally include dominated trials, while hypervolume history requires a reference point.

The launch_optuna_dashboard tool starts the Optuna dashboard and accepts an optional port, whose documented default is 58080. The optuna/optuna-mcp MCP server can use an explicitly supplied Optuna storage URI, such as a SQLite database, to persist results.

Setup and configuration

The project supports installation with uv or Docker. For a local MCP client configuration, the README uses the optuna-mcp package with uvx. A storage URI can be added with the server's --storage argument; the README demonstrates SQLite storage with sqlite:///optuna.db. Without a supplied storage argument, the material does not specify the storage behavior, so deployments that need persistence should configure storage explicitly.

Docker is also documented as an option. Its example runs the ghcr.io/optuna/optuna-mcp:latest image, mounts a local directory into /app/workspace, and passes a SQLite URI pointing to that mounted location. The Docker example uses host networking and removes the container after it exits.

The README specifically documents configuration for Claude Desktop. It instructs users to add the MCP server under the client's developer configuration and restart Claude Desktop afterward. The documented Python versions are 3.12 and 3.13.

Tools and capabilities

• Create, load, list, and inspect Optuna studies.
• Set samplers, objective directions, and metric names.
• Suggest search-space parameters and report trial results.
• Store and retrieve trial user attributes.
• Export trials as CSV and retrieve best or Pareto-front trials.
• Generate optimization and parameter-analysis plots.
• Launch the Optuna dashboard on a selected port.

Limitations and notes

The provided material describes the MCP interface and installation paths but does not identify supported sampler names, storage backends beyond the SQLite examples, or authentication mechanisms. Plot inputs vary by visualization, and several tools require an objective index, objective name, parameter list, or reference point. Dashboard access depends on the port and runtime environment selected by the client configuration.

For developers evaluating optuna/optuna-mcp MCP server, its fit is strongest when an agent must both operate an Optuna study and review its results through structured calls and generated visualizations. It is not described as a general-purpose model-training runner; the documented trial workflow handles parameter suggestion and objective-value reporting.