# optuna/optuna-mcp [Verified] [Health: Active]

**Category:** 🧮 Data Science Tools  
**Repository:** https://github.com/optuna/optuna-mcp  
**GitHub Stars:** 84  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/optuna-optuna-mcp

## Description
Official MCP server enabling seamless orchestration of hyperparameter search and other optimization tasks with Optuna.

## Tools
Capabilities this server exposes over MCP:

- **create_study** — Create a new Optuna study with the given study_name and directions.
- **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.
- **get_directions** — Get the directions of the study.
- **get_trials** — Get all trials in a CSV format.
- **best_trial** — Get the best trial.
- **best_trials** — Return trials located at the Pareto front in the study.
- **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.
- **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.
- **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).
- **plot_parallel_coordinate** — Return the parallel coordinate plot as an image.
- **plot_slice** — Return the slice plot as an image.
- **plot_param_importances** — Return the parameter importances plot as an image.
- **plot_edf** — Return the EDF plot as an image.
- **plot_timeline** — Return the timeline plot as an image.
- **plot_rank** — Return the rank plot as an image.
- **launch_optuna_dashboard** — Launch the Optuna dashboard.
- **port** — server port (integer, optional, default: 58080).

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "optuna-mcp": {
    "command": "npx",
    "args": ["-y","optuna-optuna-mcp"]
  }
}
```

## Documentation

## What optuna/optuna-mcp MCP server does

The optuna/optuna-mcp MCP server makes core Optuna operations available as MCP tools. It can create or load studies by name, configure optimization directions, choose a sampler, and manage metric labels. Agents can list studies, retrieve trial data as CSV, inspect the best trial, or query the Pareto front for multi-objective studies.

The server also supports the trial loop. `ask` receives a search-space dictionary and returns suggested parameters, while `tell` records one trial's objective value or values. Trial-level user attributes can be written and read using a trial number, key, and value. This makes it possible to attach metadata to individual optimization attempts.

## How it works

An MCP client calls the exposed tools and supplies the study, trial, search-space, or plotting arguments. Study creation accepts a name and optional `minimize` or `maximize` directions. Multi-objective studies can define multiple metric names and objective directions. The server uses Optuna to produce suggestions and evaluate the resulting study state when the client requests trial or analysis data.

Visualization tools return images for optimization history, hypervolume history, Pareto fronts, contours, parallel coordinates, slices, parameter importances, empirical distribution functions, timelines, and ranks. Several plots accept an objective index, objective name, or selected parameter list. Pareto-front plotting can optionally include dominated trials, while hypervolume history requires a reference point.

The `launch_optuna_dashboard` tool starts the Optuna dashboard and accepts an optional port, whose documented default is 58080. The optuna/optuna-mcp MCP server can use an explicitly supplied Optuna storage URI, such as a SQLite database, to persist results.

## Setup and configuration

The project supports installation with `uv` or Docker. For a local MCP client configuration, the README uses the `optuna-mcp` package with `uvx`. A storage URI can be added with the server's `--storage` argument; the README demonstrates SQLite storage with `sqlite:///optuna.db`. Without a supplied storage argument, the material does not specify the storage behavior, so deployments that need persistence should configure storage explicitly.

Docker is also documented as an option. Its example runs the `ghcr.io/optuna/optuna-mcp:latest` image, mounts a local directory into `/app/workspace`, and passes a SQLite URI pointing to that mounted location. The Docker example uses host networking and removes the container after it exits.

The README specifically documents configuration for Claude Desktop. It instructs users to add the MCP server under the client's developer configuration and restart Claude Desktop afterward. The documented Python versions are 3.12 and 3.13.

## Tools and capabilities

- Create, load, list, and inspect Optuna studies.
- Set samplers, objective directions, and metric names.
- Suggest search-space parameters and report trial results.
- Store and retrieve trial user attributes.
- Export trials as CSV and retrieve best or Pareto-front trials.
- Generate optimization and parameter-analysis plots.
- Launch the Optuna dashboard on a selected port.

## Limitations and notes

The provided material describes the MCP interface and installation paths but does not identify supported sampler names, storage backends beyond the SQLite examples, or authentication mechanisms. Plot inputs vary by visualization, and several tools require an objective index, objective name, parameter list, or reference point. Dashboard access depends on the port and runtime environment selected by the client configuration.

For developers evaluating optuna/optuna-mcp MCP server, its fit is strongest when an agent must both operate an Optuna study and review its results through structured calls and generated visualizations. It is not described as a general-purpose model-training runner; the documented trial workflow handles parameter suggestion and objective-value reporting.

_Full upstream README: https://allmcps.com/mcp/optuna-optuna-mcp/readme_