# optuna/optuna-mcp architecture

> Architecture diagram of the GitHub repository optuna/optuna-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/optuna/optuna-mcp
- Repository: https://github.com/optuna/optuna-mcp

## Overview

1. **What this repo is**
   - `optuna-mcp` is a Python MCP server that exposes Optuna capabilities to an MCP client such as Claude Desktop.
   - The server is the main integration boundary: the client sends tool calls over MCP, and the server translates them into Optuna study/trial/visualization operations.

2. **Primary runtime and entrypoint**
   - The package lives in `optuna_mcp/`.
   - `optuna_mcp/__main__.py` is the CLI entrypoint, which likely starts the MCP server process.
   - `optuna_mcp/server.py` is the core implementation module where tool handlers and server wiring live.
   - `optuna_mcp/version.py` and `py.typed` show this is a typed Python package intended for distribution.

3. **Main subsystem: study management**
   - One tool group manages Optuna study lifecycle and metadata: create/load study, list studies, set/get metric names, set/get directions, inspect best trial(s), and export trials.
   - This is the “control plane” for optimization state and study configuration.

4. **Main subsystem: ask/tell trial loop**
   - Another tool group wraps Optuna’s sequential optimization loop:
     - `ask` suggests a parameter set from a search space.
     - `tell` submits objective values for a trial.
     - trial user attributes can be written and read back.
   - This is the main data flow for LLM-driven or human-in-the-loop optimization: client → suggested parameters → external evaluation → result reported back to Optuna.

5. **State and persistence boundary**
   - The server is stateful only through Optuna storage.
   - README shows `--storage sqlite:///...` to persist studies across sessions, and Docker mounts a workspace directory so the storage file survives container restarts.
   - Without a storage URI, the server behavior is still study-centric, but persistence is configured externally through Optuna’s storage backend.

6. **Visualization subsystem**
   - The server exposes many Optuna visualization tools: optimization history, hypervolume history, Pareto front, contour, parallel coordinate, slice, parameter importances, EDF, timeline, and rank plots.
   - These handlers turn study data into images rather than raw data, which is important for the architecture: MCP clients receive rendered visual artifacts suitable for chat interfaces.

7. **Multi-objective support**
   - The API surface includes Pareto front, best-trials, hypervolume, directions, and metric names, so the server is designed for both single-objective and multi-objective studies.
   - That affects the architecture because several tools operate on multiple objective values and require study metadata to be consistent.

8. **Dashboard subsystem**
   - `launch_optuna_dashboard` starts a separate web dashboard process, defaulting to port `58080`.
   - This is a distinct boundary from MCP tool serving: the MCP server becomes a launcher/orchestrator for another service rather than rendering the dashboard itself.

9. **Packaging and deployment**
   - The repo supports two deployment paths: `uvx`/Python package execution and a Docker image.
   - `Dockerfile`, `pyproject.toml`, `uv.lock`, and GitHub Actions workflows show standard package build/test/publish automation.
   - The image runs as a CLI container, with local filesystem mounts used to persist Optuna storage files.

10. **Examples as usage blueprints**
   - `examples/` contains scenario-specific demos: 2D sphere optimization, FFmpeg tuning, cookie recipe optimization, Matplotlib configuration optimization, and dashboard usage.
   - These examples are not separate services; they document how the MCP tool surface is intended to be composed by a client during an optimization workflow.

11. **Testing boundary**
   - `tests/test_server.py` is the main test anchor, implying the repo’s correctness focus is on server/tool behavior rather than a broader application stack.
   - CI workflows under `.github/workflows/` validate tests, build the Docker image, and publish packages.

12. **Diagramming summary**
   - The key architecture diagram should show:
     - MCP client on one side
     - `optuna_mcp/server.py` in the middle as the protocol adapter
     - Optuna storage/study/trial APIs as the core backend
     - Optuna visualization rendering as an image-producing path
     - Optuna dashboard as a separate launched web service
     - Optional Docker/uv packaging as the deployment wrapper around the same server process

Main entry points: [`optuna_mcp/server.py`](https://github.com/optuna/optuna-mcp/blob/main/optuna_mcp/server.py) (Server), [`.github/workflows/checks.yml`](https://github.com/optuna/optuna-mcp/blob/main/.github/workflows/checks.yml) (CI workflows), [`Dockerfile`](https://github.com/optuna/optuna-mcp/tree/main/Dockerfile) (Dockerfile), [`pyproject.toml`](https://github.com/optuna/optuna-mcp/blob/main/pyproject.toml) (Python pkg)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server_module["Server<br/>MCP adapter<br/>[server.py]"]
  node_cli_entrypoint["CLI entry<br/>launcher<br/>[__main__.py]"]
  node_package_init["Package API<br/>[__init__.py]"]
  node_version_file["Version<br/>metadata<br/>[version.py]"]
  node_typed_marker["Typing marker<br/>package marker<br/>[py.typed]"]
end

subgraph group_backend["Optuna backend"]
  node_study_tools[("Studies<br/>study control")]
  node_trial_loop[("Ask/Tell<br/>trial loop")]
  node_study_meta["Metadata<br/>study config"]
  node_trial_attrs["Trial attrs<br/>trial metadata"]
  node_storage_backend[("Storage")]
  node_viz_tools["Visualizations<br/>rendering tools"]
  node_dashboard_launcher["Dashboard<br/>web launcher"]
end

subgraph group_delivery["Delivery"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_pyproject["Python pkg<br/>build config<br/>[pyproject.toml]"]
  node_lockfile["Lockfile<br/>dependency lock<br/>[uv.lock]"]
end

subgraph group_quality["Quality"]
  node_tests_server["Server tests<br/>test suite<br/>[test_server.py]"]
  node_github_actions["CI workflows<br/>automation<br/>[checks.yml]"]
end

subgraph group_examples["Examples"]
  node_example_sphere["Sphere demo<br/>example workflow"]
  node_example_ffmpeg["FFmpeg demo<br/>example workflow"]
  node_example_cookie["Cookie demo<br/>example workflow"]
  node_example_matplotlib["Matplotlib demo<br/>example workflow"]
  node_example_dashboard["Dashboard demo<br/>example workflow"]
end

node_mcp_client(("MCP client<br/>external client"))

node_mcp_client -->|"tool calls"| node_server_module
node_cli_entrypoint -->|"starts"| node_server_module
node_package_init -.->|"exports"| node_server_module
node_server_module -->|"manages"| node_study_tools
node_server_module -->|"orchestrates"| node_trial_loop
node_server_module -->|"renders"| node_viz_tools
node_server_module -->|"launches"| node_dashboard_launcher
node_study_tools -->|"uses"| node_study_meta
node_trial_loop -->|"reads/writes"| node_trial_attrs
node_study_tools -->|"persists via"| node_storage_backend
node_trial_loop -->|"persists via"| node_storage_backend
node_viz_tools -->|"reads from"| node_storage_backend
node_dashboard_launcher -->|"connects to"| node_storage_backend
node_dockerfile -->|"packages"| node_server_module
node_pyproject -->|"builds"| node_server_module
node_lockfile -.->|"pins"| node_pyproject
node_tests_server -->|"verifies"| node_server_module
node_github_actions -->|"runs"| node_tests_server
node_github_actions -->|"builds"| node_dockerfile
node_example_sphere -.->|"demonstrates"| node_trial_loop
node_example_ffmpeg -.->|"demonstrates"| node_trial_loop
node_example_cookie -.->|"demonstrates"| node_study_tools
node_example_matplotlib -.->|"demonstrates"| node_trial_loop
node_example_dashboard -.->|"demonstrates"| node_dashboard_launcher

click node_server_module "https://github.com/optuna/optuna-mcp/blob/main/optuna_mcp/server.py"
click node_cli_entrypoint "https://github.com/optuna/optuna-mcp/blob/main/optuna_mcp/__main__.py"
click node_package_init "https://github.com/optuna/optuna-mcp/blob/main/optuna_mcp/__init__.py"
click node_version_file "https://github.com/optuna/optuna-mcp/blob/main/optuna_mcp/version.py"
click node_typed_marker "https://github.com/optuna/optuna-mcp/blob/main/optuna_mcp/py.typed"
click node_dockerfile "https://github.com/optuna/optuna-mcp/tree/main/Dockerfile"
click node_pyproject "https://github.com/optuna/optuna-mcp/blob/main/pyproject.toml"
click node_lockfile "https://github.com/optuna/optuna-mcp/blob/main/uv.lock"
click node_tests_server "https://github.com/optuna/optuna-mcp/blob/main/tests/test_server.py"
click node_github_actions "https://github.com/optuna/optuna-mcp/blob/main/.github/workflows/checks.yml"
click node_example_sphere "https://github.com/optuna/optuna-mcp/tree/main/examples/sphere2d"
click node_example_ffmpeg "https://github.com/optuna/optuna-mcp/tree/main/examples/ffmpeg"
click node_example_cookie "https://github.com/optuna/optuna-mcp/tree/main/examples/cookie-recipe"
click node_example_matplotlib "https://github.com/optuna/optuna-mcp/tree/main/examples/auto-matplotlib"
click node_example_dashboard "https://github.com/optuna/optuna-mcp/tree/main/examples/optuna-dashboard"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_module,node_cli_entrypoint,node_package_init,node_version_file,node_typed_marker toneBlue
class node_study_tools,node_trial_loop,node_study_meta,node_trial_attrs,node_storage_backend,node_viz_tools,node_dashboard_launcher toneAmber
class node_dockerfile,node_pyproject,node_lockfile toneMint
class node_tests_server,node_github_actions toneRose
class node_example_sphere,node_example_ffmpeg,node_example_cookie,node_example_matplotlib,node_example_dashboard toneIndigo
class node_mcp_client toneNeutral
```

## Components

### Runtime

MCP server package and its main entrypoint

- [Server](https://github.com/optuna/optuna-mcp/blob/main/optuna_mcp/server.py): MCP adapter · Core server implementation and tool wiring · `optuna_mcp/server.py`
- [CLI entry](https://github.com/optuna/optuna-mcp/blob/main/optuna_mcp/__main__.py): launcher · Package entrypoint that starts the server process · `optuna_mcp/__main__.py`
- [Package API](https://github.com/optuna/optuna-mcp/blob/main/optuna_mcp/__init__.py): package · Top-level package export surface · `optuna_mcp/__init__.py`
- [Version](https://github.com/optuna/optuna-mcp/blob/main/optuna_mcp/version.py): metadata · Package version metadata · `optuna_mcp/version.py`
- [Typing marker](https://github.com/optuna/optuna-mcp/blob/main/optuna_mcp/py.typed): package marker · PEP 561 type information marker · `optuna_mcp/py.typed`

### Optuna backend

Study, trial, visualization, and dashboard capabilities exposed by the server

- **Studies**: study control · Create, load, inspect, and export studies
- **Ask/Tell**: trial loop · Sequential optimization loop for suggesting and reporting trials
- **Metadata**: study config · Metric names, directions, and best-trial related metadata
- **Trial attrs**: trial metadata · Read and write user attributes on trials
- **Storage**: optuna storage · Persistent backend configured externally, such as SQLite
- **Visualizations**: rendering tools · Optimization history, Pareto, contour, slice, importances, EDF, timeline, and rank plots
- **Dashboard**: web launcher · Launches the separate Optuna Dashboard process

### Delivery

Packaging and deployment surfaces

- [Dockerfile](https://github.com/optuna/optuna-mcp/tree/main/Dockerfile): container build · Container image for running the MCP server · `Dockerfile`
- [Python pkg](https://github.com/optuna/optuna-mcp/blob/main/pyproject.toml): build config · Package metadata, dependencies, and build settings · `pyproject.toml`
- [Lockfile](https://github.com/optuna/optuna-mcp/blob/main/uv.lock): dependency lock · Pinned dependency resolution for the Python environment · `uv.lock`

### Quality

Tests and CI automation

- [Server tests](https://github.com/optuna/optuna-mcp/blob/main/tests/test_server.py): test suite · Primary automated tests for server behavior · `tests/test_server.py`
- [CI workflows](https://github.com/optuna/optuna-mcp/blob/main/.github/workflows/checks.yml): automation · Checks, Docker image build, tests, and publish workflows · `.github/workflows/checks.yml`

### Examples

Usage scenarios that demonstrate the tool surface

- [Sphere demo](https://github.com/optuna/optuna-mcp/tree/main/examples/sphere2d): example workflow · Simple optimization walkthrough · `examples/sphere2d`
- [FFmpeg demo](https://github.com/optuna/optuna-mcp/tree/main/examples/ffmpeg): example workflow · Tuning example for media-processing parameters · `examples/ffmpeg`
- [Cookie demo](https://github.com/optuna/optuna-mcp/tree/main/examples/cookie-recipe): example workflow · Recipe optimization example · `examples/cookie-recipe`
- [Matplotlib demo](https://github.com/optuna/optuna-mcp/tree/main/examples/auto-matplotlib): example workflow · Configuration optimization example and local server demo · `examples/auto-matplotlib`
- [Dashboard demo](https://github.com/optuna/optuna-mcp/tree/main/examples/optuna-dashboard): example workflow · Usage example for launching the dashboard · `examples/optuna-dashboard`

### Other components

- **MCP client**: external client · Claude Desktop or another MCP consumer that issues tool calls

## Connections

- MCP client → Server: tool calls · Client sends MCP requests to the server
- CLI entry → Server: starts · CLI launches the MCP server process
- Package API → Server: exports · Package surface points to server implementation
- Server → Studies: manages · Study lifecycle and inspection operations
- Server → Ask/Tell: orchestrates · Ask/tell trial workflow
- Server → Visualizations: renders · Produces visualization artifacts from study data
- Server → Dashboard: launches · Starts a separate Optuna Dashboard service
- Studies → Metadata: uses · Study operations depend on metadata consistency
- Ask/Tell → Trial attrs: reads/writes · Trial loop exposes user attributes
- Studies → Storage: persists via · Studies are stored through Optuna storage
- Ask/Tell → Storage: persists via · Trial state and results go through Optuna storage
- Visualizations → Storage: reads from · Plots are derived from stored study and trial data
- Dashboard → Storage: connects to · Dashboard reads the same underlying studies
- Dockerfile → Server: packages · Container image runs the MCP server
- Python pkg → Server: builds · Python package defines the server distribution
- Lockfile → Python pkg: pins · Dependency resolution for the package build
- Server tests → Server: verifies · Tests focus on server/tool behavior
- CI workflows → Server tests: runs · CI executes the test suite
- CI workflows → Dockerfile: builds · CI validates the container image
- Sphere demo → Ask/Tell: demonstrates · Shows ask/tell optimization flow
- FFmpeg demo → Ask/Tell: demonstrates · Shows parameter tuning workflow
- Cookie demo → Studies: demonstrates · Shows study-oriented optimization usage
- Matplotlib demo → Ask/Tell: demonstrates · Shows iterative tuning and local execution
- Dashboard demo → Dashboard: demonstrates · Shows dashboard launch and usage
