optuna/optuna-mcp

A Model Context Protocol (MCP) server that automates optimization and analysis using Optuna.
Use Cases
The Optuna MCP Server can be used in the following use cases, for example.
- Automated hyperparameter optimization by LLMs
- Interactive analysis of Optuna's optimization results via chat interface
- Optimize input and output of other MCP tools
For details, see the Examples section.
Installation
The Optuna MCP server can be installed using uv or Docker.
This section explains how to install the Optuna MCP server, using Claude Desktop as an example MCP client.
Usage with uv
Before starting the installation process, install uv from Astral.
Then, add the Optuna MCP server configuration to the MCP client.
To include it in Claude Desktop, go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json
and add the following:
Additionally, you can specify the Optuna storage with the --storage argument to persist the results.
After adding this, please restart Claude Desktop application.
For more information about Claude Desktop, check out the quickstart page.
Usage with Docker
You can also run the Optuna MCP server using Docker. Make sure you have Docker installed and running on your machine.
Tools provided by Optuna MCP
The Optuna MCP provides the following tools.
Specifically, it offers primitive functions of Optuna such as Study, Trial, Visualization, and Dashboard.
Since MCP clients know the list of tools and the details of each tool, users do not need to remember those details.
Study
- **create_study** - Create a new Optuna study with the given study_name and directions.
If the study already exists, it will be simply loaded.
- study_name : name of the study (string, required).
- directions: The directions of optimization (list of literal strings minimize/maximize, optional).
- **set_sampler** - Set the sampler for the study.
- name : the name of the sampler (string, required).
- **get_all_study_names** - Get all study names from the storage.
- **set_metric_names** - Set metric_names. Metric_names are labels used to distinguish what each objective value is.
- metric_names : The list of metric names for each objective (list of strings, required).
- **get_metric_names** - Get metric_names.
- No parameters required.
- **get_directions** - Get the directions of the study.
- No parameters required.
- **get_trials** - Get all trials in a CSV format.
- No parameters required.
- **best_trial** - Get the best trial.
- No parameters required.
- **best_trials** - Return trials located at the Pareto front in the study.
- No parameters required.
Trial
- **ask** - Suggest new parameters using Optuna.
- search_space : the search space for Optuna (dictionary, required).
- **tell** - Report the result of a trial.
- trial_number : the trial number (integer, required).
- values : the result of the trial (float or list of floats, required).
- **set_trial_user_attr** - Set user attributes for a trial.
- trial_number: the trial number (integer, required).
- key: the key of the user attribute (string, required).
- value: the value of the user attribute (any type, required).
- **get_trial_user_attrs** - Get user attributes in a trial.
- trial_number: the trial number (integer, required).
Visualization
- **plot_optimization_history** - Return the optimization history plot as an image.
- target: index to specify which value to display (integer, optional).
- target_name: target’s name to display on the axis label (string, optional).
- **plot_hypervolume_history** - Return the hypervolume history plot as an image.