Optuna MCP Server
Featuredby
Interact with Optuna APIs through Model Context Protocol, providing primitive functions for study management, trial suggestion, result reporting, visualizations, and a web dashboard.
Optuna MCP Server Overview
What is Optuna MCP Server about?
Enables automated hyperparameter optimization and analysis by exposing Optuna's core functionality as MCP tools. Clients can create studies, suggest and evaluate trials, retrieve metrics, and generate a variety of plots without writing Optuna code directly.
How to use Optuna MCP Server?
- Install
- Using uv:
uvx optuna-mcp - Using Docker:
docker run -i --rm --net=host -v /local/path:/app/workspace optuna/optuna-mcp:latest --storage sqlite:////app/workspace/optuna.db
- Using uv:
- Configure the MCP client (e.g., Claude Desktop) by adding a server entry:
Add{ "mcpServers": { "Optuna": { "command": "uvx", "args": ["optuna-mcp"] } } }--storagearguments if you need persistent storage. - Interact via chat or programmatic calls, invoking tools such as
create_study,ask,tell, orplot_optimization_history.
Key Features
- Study management: create/load studies, set samplers, list study names, define metric names, retrieve directions, fetch all trials, get best trial(s).
- Trial workflow: suggest parameters (
ask), report results (tell), manage user attributes. - Rich visualizations: optimization history, hypervolume, Pareto front, contour, parallel coordinate, slice, parameter importances, EDF, timeline, rank plots.
- Web dashboard: launch Optuna dashboard on a configurable port for interactive analysis.
- Docker & uv support: flexible deployment options.
Use Cases
- Automated hyperparameter tuning driven by LLMs.
- Interactive exploration of optimization results via chat interfaces.
- Integrating Optuna optimization into other MCP‑compatible tools.
- Running multi‑objective optimization with on‑the‑fly visual feedback.
- Persisting and reviewing studies through the Optuna dashboard.
FAQ
- Do I need a local Optuna installation? No. The server bundles Optuna; just install the MCP server.
- Can I use a custom storage backend? Yes, pass
--storage <SQLALCHEMY_URL>when starting the server. - Which Python versions are supported? Python 3.12 and 3.13.
- How are plots returned? As image bytes that MCP clients can render directly.
- Is the server thread‑safe? The underlying Optuna study handles concurrency; the MCP wrapper forwards calls safely.
Optuna MCP Server's README
Optuna MCP Server
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:
{
"mcpServers": {
"Optuna": {
"command": "uvx",
"args": [
"optuna-mcp"
]
}
}
}
Additionally, you can specify the Optuna storage with the --storage argument to persist the results.
{
"mcpServers": {
"Optuna": {
"command": "uvx",
"args": [
"optuna-mcp"
"--storage",
"sqlite:///optuna.db"
]
}
}
}
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.
{
"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"
]
}
}
}
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.
reference_point: a list of reference points to calculate the hypervolume (list of floats, required).
- plot_pareto_front - Return the Pareto front plot as an image for multi-objective optimization.
target_names: objective name list used as the axis titles (list of strings, optional).include_dominated_trials: a flag to include all dominated trial's objective values (boolean, optional).targets: a list of indices to specify the objective values to display. (list of integers, optional).
- plot_contour - Return the contour plot as an image.
params: parameter list to visualize (list of strings, optional).target: an index to specify the value to display (integer, required).target_name: target’s name to display on the color bar (string, required).
- plot_parallel_coordinate - Return the parallel coordinate plot as an image.
params: parameter list to visualize (list of strings, optional).target: an index to specify the value to display (integer, required).target_name: target’s name to display on the axis label and the legend (string, required).
- plot_slice - Return the slice plot as an image.
params: parameter list to visualize (list of strings, optional).target: an index to specify the value to display (integer, required).target_name: target’s name to display on the axis label (string, required).
- plot_param_importances - Return the parameter importances plot as an image.
params: parameter list to visualize (list of strings, optional).target: an index to specify the value to display (integer/null, optional).target_name: target’s name to display on the legend (string, required).
- plot_edf - Return the EDF plot as an image.
target: an index to specify the value to display (integer, required).target_name: target’s name to display on the axis label (string, required).
- plot_timeline - Return the timeline plot as an image.
- No parameters required.
- plot_rank - Return the rank plot as an image.
params: parameter list to visualize (list of strings, optional).target: an index to specify the value to display (integer, required).target_name: target’s name to display on the color bar (string, required).
Web Dashboard
- launch_optuna_dashboard - Launch the Optuna dashboard.
port: server port (integer, optional, default: 58080).
Examples
- Optimizing the 2D-Sphere function
- Starting the Optuna dashboard and analyzing optimization results
- Optimizing the FFmpeg encoding parameters
- Optimizing the Cookie Recipe
- Optimizing the Matplotlib Configuration
Optimizing the 2D-Sphere Function
Here we present a simple example of optimizing the 2D-Sphere function, along with example prompts and the summary of the LLM responses.
| User prompt | Output in Claude |
|---|---|
| (Launch Claude Desktop) | |
| Please create an Optuna study named "Optimize-2D-Sphere" for minimization. | |
| Please suggest two float parameters x, y in [-1, 1]. | |
| Please report the objective value x**2 + y**2. To calculate the value, please use the JavaScript interpreter and do not round the values. | |
| Please suggest another parameter set and evaluate it. | |
| Please plot the optimization history so far. |
Starting the Optuna Dashboard and Analyzing Optimization Results
You can also start the Optuna dashboard via the MCP server to analyze the optimization results interactively.
| User prompt | Output in Claude |
|---|---|
| Please launch the Optuna dashboard. |
By default, the Optuna dashboard will be launched on port 58080.
You can access it by navigating to http://localhost:58080 in your web browser as shown below:
Optuna dashboard provides various visualizations to analyze the optimization results, such as optimization history, parameter importances, and more.
Optimizing the FFmpeg Encoding Parameters
This demo showcases how to use the Optuna MCP server to automatically find optimal FFmpeg encoding parameters. It optimizes x264 encoding options to maximize video quality (measured by the SSIM score) while keeping encoding time reasonable.
Check out examples/ffmpeg for details.
Optimizing the Cookie Recipe
In this example, we will optimize a cookie recipe, referencing the paper titled "Bayesian Optimization for a Better Dessert".
Check out examples/cookie-recipe for details.
Optimizing the Matplotlib Configuration
This example optimizes a Matplotlib configuration.
Check out examples/auto-matplotlib for details.
License
MIT License (see LICENSE).
Optuna MCP Server Reviews
Login Required
Please log in to share your review and rating for this MCP.
Actions
Optuna MCP Server's Information
- Author
- optuna
- Category
- Development Tools
- Language
- Python
- License
- MIT License
- Stars
- 57
- Updated
- 1 month ago
Similar MCP Servers like Optuna MCP Server
Explore related MCPs that share similar capabilities and solve comparable challenges
Zed
OfficialClientby zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
Everything
Officialby modelcontextprotocol
Model Context Protocol Servers
Git
Officialby modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
Time
Officialby modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
Cline
OfficialClientby cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
Continue
OfficialClientby continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
Context7 MCP
Officialby upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
GitHub MCP Server
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.
Daytona
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.