Optuna MCP

🚀 Optuna MCP Server

An MCP server automating optimization and analysis with Optuna.

🚀 Quick Start

The Optuna MCP Server is a Model Context Protocol (MCP) server that automates optimization and analysis using Optuna.

✨ Features

The Optuna MCP Server can be used in the following scenarios:

• Automated hyperparameter optimization by LLMs.
• Interactive analysis of Optuna's optimization results via chat interface.
• Optimization of input and output for other MCP tools.

For more details, refer to the Examples section.

📦 Installation

The Optuna MCP server can be installed using uv or Docker. This section explains how to install the server, using Claude Desktop as an example MCP client.

Usage with uv

Before starting the installation, 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, restart the 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 Docker is 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"
      ]
    }
  }
}

💻 Usage Examples

Basic Usage

The Optuna MCP provides a series of tools, including functions related to Study, Trial, Visualization, and Dashboard.

Tools provided by Optuna MCP

The Optuna MCP offers the following tools, which are primitive functions of Optuna. Since MCP clients know the list of tools and their details, users don't need to remember them.

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).

Advanced Usage

Here are some practical examples of using the Optuna MCP server.

Optimizing the 2D-Sphere Function

This is a simple example of optimizing the 2D-Sphere function, with example prompts and summaries of LLM responses.

Starting the Optuna Dashboard and Analyzing Optimization Results

You can start the Optuna dashboard via the MCP server to analyze the optimization results interactively.

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. The dashboard provides various visualizations for analyzing optimization results, such as optimization history and parameter importances.

Optimizing the FFmpeg Encoding Parameters

This demo shows 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.md for details.

Optimizing the Cookie Recipe

In this example, we optimize a cookie recipe, referencing the paper "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

This project is under the MIT License (see LICENSE).