How optuna/optuna-mcp works
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: server.py Server · checks.yml CI workflows · Dockerfile Dockerfile · pyproject.toml Python pkg
Components 23
Runtime
MCP server package and its main entrypoint
- Server · Core server implementation and tool wiring
optuna_mcp/server.py - CLI entry · Package entrypoint that starts the server process
optuna_mcp/__main__.py - Package API · Top-level package export surface
optuna_mcp/__init__.py - Version · Package version metadata
optuna_mcp/version.py - Typing marker · PEP 561 type information marker
optuna_mcp/py.typed
Optuna backend
Study, trial, visualization, and dashboard capabilities exposed by the server
- Studies · Create, load, inspect, and export studies
- Ask/Tell · Sequential optimization loop for suggesting and reporting trials
- Metadata · Metric names, directions, and best-trial related metadata
- Trial attrs · Read and write user attributes on trials
- Storage · Persistent backend configured externally, such as SQLite
- Visualizations · Optimization history, Pareto, contour, slice, importances, EDF, timeline, and rank plots
- Dashboard · Launches the separate Optuna Dashboard process
Delivery
Packaging and deployment surfaces
- Dockerfile · Container image for running the MCP server
Dockerfile - Python pkg · Package metadata, dependencies, and build settings
pyproject.toml - Lockfile · Pinned dependency resolution for the Python environment
uv.lock
Quality
Tests and CI automation
- Server tests · Primary automated tests for server behavior
tests/test_server.py - CI workflows · Checks, Docker image build, tests, and publish workflows
.github/workflows/checks.yml
Examples
Usage scenarios that demonstrate the tool surface
- Sphere demo · Simple optimization walkthrough
examples/sphere2d - FFmpeg demo · Tuning example for media-processing parameters
examples/ffmpeg - Cookie demo · Recipe optimization example
examples/cookie-recipe - Matplotlib demo · Configuration optimization example and local server demo
examples/auto-matplotlib - Dashboard demo · Usage example for launching the dashboard
examples/optuna-dashboard
Other components
- MCP client · Claude Desktop or another MCP consumer that issues tool calls
Connections 24
- 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