Optuna MCP Server for Hyperparameter Optimization

Overview

The Optuna MCP Server implements a central Model Context Protocol (MCP) endpoint that coordinates Optuna-based hyperparameter optimization. It provides a lightweight service that exposes a consistent HTTP/gRPC API for creating studies, requesting trial suggestions, and reporting trial outcomes. By separating the suggestion/observation logic from worker code, the MCP server simplifies distributed tuning across fleets of trainers, CI pipelines, and managed compute resources.

This server is useful when you need reproducible, scalable hyperparameter search without embedding Optuna’s storage and suggestion logic inside every training process. The MCP server centralizes study state, persists trials in a database, and makes it easier to orchestrate parallel workers, enforce multi-tenancy, and integrate optimization into existing infrastructure.

Features

• Centralized Optuna study management with persistent storage (SQLAlchemy-backed).
• MCP-compatible API (HTTP and/or gRPC) to perform suggest/observe operations.
• Support for distributed workers: a single server can serve suggestions to multiple clients concurrently.
• Configurable backend storage (SQLite, PostgreSQL, MySQL) to scale from local experiments to production.
• CLI and Docker-friendly deployment patterns for rapid local testing and production rollout.
• Basic observability: logging and configurable log level.
• Authentication and multi-tenant study isolation (configurable through environment settings or middleware).
• Extensible: integrates into CI systems, training orchestration, and model-serving workflows.

Installation / Configuration

Install from PyPI (if released) or run from source.

Install (PyPI)

pip install optuna-mcp

Run from source (development)

git clone https://github.com/optuna/optuna-mcp.git
cd optuna-mcp
pip install -e .
# Start the server with an ASGI server (example uses uvicorn)
uvicorn optuna_mcp.main:app --host 0.0.0.0 --port 8080

Docker (example)

# Build a local image
docker build -t optuna-mcp:local .

# Run exposing port 8080 and a SQLite file in a mounted directory
docker run -p 8080:8080 -v $(pwd)/data:/data \
  -e OPTUNA_STORAGE_URL=sqlite:////data/optuna.db \
  optuna-mcp:local

Recommended environment configuration

Docker Compose snippet

version: "3.7"
services:
  optuna-mcp:
    image: optuna-mcp:local
    ports:
      - "8080:8080"
    environment:
      - OPTUNA_STORAGE_URL=postgresql://optuna:password@db/optuna
      - LOG_LEVEL=INFO
    depends_on:
      - db
  db:
    image: postgres:14
    environment:
      - POSTGRES_USER=optuna
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=optuna
    volumes:
      - db-data:/var/lib/postgresql/data
volumes:
  db-data:

Available Resources

• Repository: https://github.com/optuna/optuna-mcp
• Optuna docs: https://optuna.readthedocs.io
• MCP specification / API docs: check the repository’s API docs or OpenAPI schema for available endpoints
• Examples and integration tests: included in the repository under examples/ or tests/ (see source)

Use Cases

1. Distributed hyperparameter tuning across GPU workers

   • Deploy a single optuna-mcp server connected to a PostgreSQL instance.
   • Start many trainer processes (on different machines or Kubernetes pods) that call the MCP server to request parameter suggestions and then report observed metrics back.
   • The server serializes trial allocation and maintains a global view of the study, enabling efficient parallel search.

2. Automated tuning in CI/CD pipelines

   • Use the MCP server to run short hyperparameter sweeps for pull requests.
   • Each CI job requests a few trials and reports results; the server stores all runs, so teams can compare tunings and reproduce candidate configurations.

3. Multi-tenant tuning service inside a platform