Optuna MCP

by optuna

Runs Optuna studies through MCP, covering parameter suggestions, trial results, plots, Pareto analysis, and the Optuna dashboard.

Data Science Tools
88stars
No ratings
UpdatedOct 22, 2026

InstallRepository Website

Install Optuna MCP

Pick your client, then add it in one click or paste the config.

STDIOPython

~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "optuna-optuna-mcp": {
      "command": "uvx",
      "args": [
        "optuna-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

uvx optuna-mcp

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 5d ago.

Overview

Python

The optuna/optuna-mcp MCP server exposes Optuna study management, trial evaluation, visualization, and dashboard controls to MCP clients. Agents can create or load studies, configure samplers and metrics, request parameter suggestions, submit objective values, and inspect results. It supports single- and multi-objective workflows, including Pareto-front and hypervolume analysis. Reach for it when an MCP client needs to drive or explain Optuna optimization interactively.

Use cases

Create Optuna studies for automated hyperparameter searches
Suggest parameters and record objective values through chat
Inspect optimization results with CSV data and plots
Analyze Pareto fronts and hypervolume for multi-objective studies
Launch the Optuna dashboard for interactive result review

Key features

Study and sampler management
Ask-and-tell trial workflow
Single- and multi-objective optimization support
Trial metadata attributes
Optimization and parameter visualizations
Optuna dashboard launch

Tools41

What Optuna MCP lets your agent do. Expand a tool for its parameters.

Self-reported~631 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

14/15 checks healthy over the last 79d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 6d ago via OSV.dev · optuna-mcp (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars88Stargazers on the source repository.

Last commit6d agoMost recent push to the default branch.

Install checkInconclusiveDidn't respond in our test window — often a slow first install.

Tools exposed41Callable tools this server registers over MCP.

Directory activity6 viewsConfig copies, upvotes, and views on AllMCPs.

How Optuna MCP works

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

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Optuna MCP

Install it with uv and configure an MCP client to run the optuna-mcp package with uvx. Docker is also documented as an installation option.

Yes. The README provides Claude Desktop configuration examples and instructs users to restart the application after editing its MCP configuration.

Pass an Optuna storage URI with the --storage argument. The README demonstrates SQLite storage using sqlite:///optuna.db.

Yes. Studies can use multiple directions and metric names, and the server includes Pareto-front and hypervolume tools.

It provides optimization history, hypervolume history, Pareto-front, contour, parallel-coordinate, slice, parameter-importance, EDF, timeline, and rank plots.

Related MCP servers

All in Data Science Tools All alternatives

Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/optuna-optuna-mcp?style=directory)](https://allmcps.com/mcp/optuna-optuna-mcp)

HTML Embed

<a href="https://allmcps.com/mcp/optuna-optuna-mcp"><img src="https://allmcps.com/api/badge/optuna-optuna-mcp?style=directory" alt="Optuna MCP on AllMCPs" /></a>