Optuna

The Optuna MCP Server automates optimization and analysis tasks using Optuna within a Model Context Protocol environment. It enables automated hyperparameter tuning, interactive exploration of optimization results, and seamless integration with other MCP tools to streamline experimentation and results-driven decisions.

How to use

You interact with the Optuna MCP Server through an MCP client. Start by running the server in stdio mode (local process) or in a container, then configure your MCP client to connect to it. Use the server to create studies, propose and evaluate trials, and visualize optimization progress. You can also launch a dashboard to inspect optimization history and parameter importances.

How to install

Prerequisites: ensure you have an MCP client installed and ready to configure. You also need a runtime capable of starting the Optuna MCP Server either as a local process or inside Docker.

Configure the MCP client for UVX (stdio) use

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

Configure the MCP client for Docker (stdio) use

{
  "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"
      ]
    }
  },
  "envVars": []
}

Tools provided by Optuna MCP

The Optuna MCP Server exposes a set of primitive Optuna capabilities that you can use through the MCP interface. These include study management, trial interaction, and visualization tools.

Study

create_study creates a new Optuna study or loads an existing one. You can specify the study name and optimization directions. set_sampler selects the sampler for a study. get_all_study_names lists all stored studies. set_metric_names assigns labels to objective values. get_metric_names retrieves them. get_directions returns current optimization directions. get_trials exports trials as CSV. best_trial and best_trials fetch top-performing results.

Trial

ask proposes new parameter sets based on the defined search space. tell submits the evaluation result for a given trial. set_trial_user_attr attaches user-defined metadata to a trial. get_trial_user_attrs retrieves those attributes.

Visualization

plot_optimization_history returns a chart of objective values over time. plot_hypervolume_history requires a reference point to compute hypervolume. plot_pareto_front visualizes Pareto-optimal solutions. plot_contour, plot_parallel_coordinate, plot_slice, plot_param_importances, plot_edf, plot_timeline, and plot_rank generate respective visualizations to analyze multi-objective performance and parameter importance.

Web Dashboard

launch_optuna_dashboard starts the optional interactive dashboard for live visualization of optimization results. You can specify a port (default is 58080) to access the dashboard in a browser.

Examples

Explore common scenarios like optimizing a simple objective, tuning encoding or rendering parameters, or adjusting plotting configurations to gain intuition about the optimization process.

Notes and troubleshooting

If you encounter connection issues, verify that the MCP client is pointed at the correct stdio server instance and that the storage backend is accessible. For Docker-based runs, ensure Docker is running and that the host path for the workspace directory exists and is writable.

Security considerations

Limit access to the Optuna MCP Server to trusted clients. Use network controls and, where possible, authentication or access tokens when exposing the server to external networks.

Available tools

create_study

Create a new Optuna study with a given name and optimization directions; loads existing studies if the name already exists.

set_sampler

Choose a sampler by name for a study to influence trial generation.

get_all_study_names

Retrieve all stored study names from the storage backend.

set_metric_names

Define labels for objective values to distinguish what each objective represents.

get_metric_names

Retrieve the labels assigned to each objective.

get_directions

Return the current optimization directions (minimize or maximize) for a study.

get_trials

Export all trials in a CSV format for external analysis.

best_trial

Fetch the single best-performing trial in the study.

best_trials

Return trials located at the Pareto front in multi-objective scenarios.

ask

Propose new parameter configurations based on the defined search space.

tell

Submit the results of a trial, including objective values.

set_trial_user_attr

Attach custom user attributes to a specific trial.

get_trial_user_attrs

Retrieve user attributes associated with a specific trial.

plot_optimization_history

Generate a visualization of the optimization history.

plot_hypervolume_history

Create a hypervolume history visualization given a reference point.

plot_pareto_front

Show the Pareto front with optional axis labels and settings.

plot_contour

Produce a contour plot of objective values across parameter space.

plot_parallel_coordinate

Visualize multi-parameter trajectories with a parallel coordinates plot.

plot_slice

Display slice plots to inspect parameter effects.

plot_param_importances

Show how much each parameter contributes to the optimization result.

plot_edf

Plot the empirical distribution function of objective values.

plot_timeline

Provide a timeline visualization of optimization progress.

plot_rank

Render a rank-based visualization for comparisons among trials.

launch_optuna_dashboard

Launch the Optuna dashboard for interactive exploration of results.