Optuna MCP Server
OfficialThe Optuna MCP Server enables automated hyperparameter optimization and analysis through LLMs by providing access to Optuna's capabilities via the Model Context Protocol.
Core Capabilities:
Study Management: Create and manage studies with configurable optimization directions (minimize/maximize), define samplers (TPESampler, NSGAIISampler, RandomSampler, GPSampler), set metric names for multi-objective optimization, and retrieve study information
Trial Operations: Request suggested parameters using Optuna's distribution system (ask), report objective values (tell), manually add single or batch trials, and manage trial metadata through user attributes
Results Analysis: Retrieve all trials in CSV format, find the best trial for single-objective optimization, or get trials on the Pareto front for multi-objective problems
Visualization: Generate plots including optimization history, hypervolume history, Pareto front, contour maps, parallel coordinates, slice plots, parameter importances, EDF plots, timeline, and rank plots
Interactive Analysis: Launch the Optuna dashboard (default port 58080) for web-based interactive study analysis
Persistent Storage: Support for SQLite and other storage backends to maintain optimization history
Use Cases:
Automated hyperparameter optimization for ML models guided by LLMs
Interactive optimization and result analysis via chat interfaces
Optimizing parameters for other MCP tools and applications (FFmpeg encoding, matplotlib configurations, recipes)
Multi-objective optimization with Pareto front analysis
Enables running the Optuna MCP server in a containerized environment with volume mounting for persistence of optimization results.
Provides tools for optimizing FFmpeg encoding parameters to maximize video quality while balancing encoding time.
Allows use of JavaScript interpreter to calculate objective values for optimization problems.
Integrates with Python environment, offering access to Optuna's hyperparameter optimization capabilities through a standardized interface.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Optuna MCP Server create a study named 'xgboost_tuning' to minimize validation loss"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: FastAPI MCP Server
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": "/path/to/uvx",
"args": [
"optuna-mcp"
]
}
}
}Additionally, you can specify the Optuna storage with the --storage argument to persist the results.
{
"mcpServers": {
"Optuna": {
"command": "/path/to/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",
"ghcr.io/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
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).
Available Tools
26 toolsadd_trialC
Add a trial to the study.
Inputs: trial (required). Returns: result
add_trialsC
Add multiple trials to the study.
Inputs: trials (required). Returns: result
askC
Suggest new parameters using Optuna
search_space must be a string that can be evaluated to a dictionary to specify Optuna's distributions.
Example:
{"x": {"name": "FloatDistribution", "attributes": {"step": null, "low": -10.0, "high": 10.0, "log": false}}}
Inputs: search_space (required). Returns: trial_number, params, values, user_attrs, +1 more
best_trialA
Get the best trial
This feature can only be used for single-objective optimization. If your study is multi-objective, use best_trials instead.
Inputs: no named parameters. Returns: trial_number, params, values, user_attrs, +1 more
best_trialsA
Return trials located at the Pareto front in the study.
Inputs: no named parameters. Returns: result
create_studyC
Create a new Optuna study with the given study_name and directions.
If the study already exists, it will be simply loaded.
Inputs: study_name (required), directions. Returns: study_name, sampler_name, directions, metric_names
get_all_study_namesC
Get all study names from the storage.
Inputs: no named parameters. Returns: result
get_directionsC
Get the directions of the study.
Inputs: no named parameters. Returns: study_name, sampler_name, directions, metric_names
get_metric_namesD
Get metric_names
Inputs: no named parameters. Returns: study_name, sampler_name, directions, metric_names
get_trialsA
Get all trials in a CSV format
Inputs: no named parameters.
get_trial_user_attrsC
Get user attributes in a trial
Inputs: trial_number (required). Returns: trial_number, params, values, user_attrs, +1 more
launch_optuna_dashboardC
Launch the Optuna dashboard
Inputs: port. Returns: result
plot_contourB
Return the contour plot as an image.
Args:
params:
Parameter list to visualize. The default is all parameters.
target:
An index to specify the value to display. To plot nth objective value, set this to n.
Note that this is 0-indexed, i.e., to plot the first objective value, set this to 0.
target_name:
Target’s name to display on the color bar.
Inputs: params, target, target_name.
plot_edfC
Return the EDF plot as an image.
Args:
target:
An index to specify the value to display. To plot nth objective value, set this to n.
Note that this is 0-indexed, i.e., to plot the first objective value, set this to 0.
target_name:
Target’s name to display on the axis label.
Inputs: target, target_name.
plot_hypervolume_historyC
Return the hypervolume history plot as an image.
Args:
reference_point:
A list of reference points to calculate the hypervolume.
Inputs: reference_point (required).
plot_optimization_historyA
Return the optimization history plot as an image.
Args:
target:
An index to specify the value to display. To plot nth objective value, set this to n.
Note that this is 0-indexed, i.e., to plot the first objective value, set this to 0.
For single-objective optimization, None (auto) is recommended.
For multi-objective optimization, this must be specified.
target_name:
Target's name to display on the axis label and the legend.
Inputs: target, target_name.
plot_parallel_coordinateB
Return the parallel coordinate plot as an image.
Args:
params:
Parameter list to visualize. The default is all parameters.
target:
An index to specify the value to display. To plot nth objective value, set this to n.
Note that this is 0-indexed, i.e., to plot the first objective value, set this to 0.
target_name:
Target’s name to display on the axis label and the legend.
Inputs: params, target, target_name.
plot_param_importancesA
Return the parameter importances plot as an image.
Args:
params:
Parameter list to visualize. The default is all parameters.
target:
An index to specify the value to display. To plot nth objective value, set this to n.
Note that this is 0-indexed, i.e., to plot the first objective value, set this to 0.
By default, all objective will be plotted by setting target to None.
target_name:
Target’s name to display on the legend.
Inputs: params, target, target_name.
plot_pareto_frontA
Return the Pareto front plot as an image for multi-objective optimization.
Args:
target_names:
Objective name list used as the axis titles. If :obj:`None` is specified,
"Objective {objective_index}" is used instead. If ``targets`` is specified
for a study that does not contain any completed trial,
``target_name`` must be specified.
include_dominated_trials:
A flag to include all dominated trial's objective values.
targets:
A list of indices to specify the objective values to display.
Note that this is 0-indexed, i.e., to plot the first and second objective value, set this to [0, 1].
If the number of objectives is neither 2 nor 3, ``targets`` must be specified.
By default, all objectives are displayed.
Inputs: target_names, include_dominated_trials, targets.
plot_rankA
Return the rank plot as an image.
Args:
params:
Parameter list to visualize. The default is all parameters.
target:
An index to specify the value to display. To plot nth objective value, set this to n.
Note that this is 0-indexed, i.e., to plot the first objective value, set this to 0.
target_name:
Target’s name to display on the color bar.
Inputs: params, target, target_name.
plot_sliceC
Return the slice plot as an image.
Args:
params:
Parameter list to visualize. The default is all parameters.
target:
An index to specify the value to display. To plot nth objective value, set this to n.
Note that this is 0-indexed, i.e., to plot the first objective value, set this to 0.
target_name:
Target’s name to display on the axis label.
Inputs: params, target, target_name.
plot_timelineB
Return the timeline plot as an image.
Inputs: no named parameters.
set_metric_namesB
Set metric_names. metric_names are labels used to distinguish what each objective value is.
Args:
metric_names:
The list of metric name for each objective value.
The length of metric_names list must be the same with the number of objectives.
Inputs: metric_names (required). Returns: study_name, sampler_name, directions, metric_names
set_samplerA
Set the sampler for the study. The sampler must be one of the following: - TPESampler - NSGAIISampler - RandomSampler - GPSampler
The default sampler for single-objective optimization is TPESampler.
The default sampler for multi-objective optimization is NSGAIISampler.
GPSampler is a Gaussian process-based sampler suitable for low-dimensional numerical optimization problems.
Inputs: name (required). Returns: study_name, sampler_name, directions, metric_names
set_trial_user_attrC
Set user attributes for a trial
Inputs: trial_number (required), key (required), value (required). Returns: result
tellC
Report the result of a trial
Inputs: trial_number (required), values (required). Returns: trial_number, params, values, user_attrs, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Each tool has a clearly distinct purpose. The many plot tools are differentiated by the type of plot they generate, and the core tools like ask, tell, create_study, etc. have unique roles without overlap.
Most tools follow a verb_noun pattern (add_trial, create_study, get_trials), but a few deviate like 'ask', 'tell' (single verbs), and 'best_trial' (adjective_noun). Overall consistent enough for readability.
26 tools is above the typical range of 3-15, but each tool serves a clear purpose within the Optuna ecosystem. The count is justified by the breadth of functionality including many visualization tools.
The tool set covers the full lifecycle of hyperparameter optimization: creating studies, adding trials, suggesting/reporting results, retrieving best trials, setting samplers, and extensive analysis with plots. No obvious gaps.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
MCP server for building and testing AI agents with multi-model experimentation and insights.
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceA server that enables Large Language Models to discover and interact with REST APIs defined by OpenAPI specifications through the Model Context Protocol.12,706 npm302MIT
- AlicenseNot gradedqualityDmaintenanceA high-performance Model Context Protocol (MCP) server designed for large language models, enabling real-time communication between AI models and applications with support for session management and intelligent tool registration.2MIT
- AlicenseAqualityCmaintenanceA Model Context Protocol server that enables large language models to access database metadata and perform cross-engine data querying across diverse database ecosystems.1654Apache 2.0
- FlicenseAqualityNot gradedmaintenanceA Model Context Protocol server that allows LLMs to interact with Python environments, enabling code execution, file operations, package management, and development workflows.9-