{"id":28637691,"url":"https://github.com/optuna/optuna-mcp","last_synced_at":"2025-06-16T22:02:27.090Z","repository":{"id":298453636,"uuid":"999382530","full_name":"optuna/optuna-mcp","owner":"optuna","description":"The Optuna MCP Server is a Model Context Protocol (MCP) server to interact with Optuna APIs.","archived":false,"fork":false,"pushed_at":"2025-06-11T07:28:06.000Z","size":5143,"stargazers_count":2,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-11T07:38:39.381Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/optuna.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-10T07:03:55.000Z","updated_at":"2025-06-11T07:28:08.000Z","dependencies_parsed_at":"2025-06-11T07:39:04.269Z","dependency_job_id":"1b30ecaa-dd4e-4c79-9626-d7991cb41fdc","html_url":"https://github.com/optuna/optuna-mcp","commit_stats":null,"previous_names":["optuna/optuna-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/optuna/optuna-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optuna%2Foptuna-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optuna%2Foptuna-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optuna%2Foptuna-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optuna%2Foptuna-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/optuna","download_url":"https://codeload.github.com/optuna/optuna-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optuna%2Foptuna-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259875174,"owners_count":22925122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-12T18:30:33.910Z","updated_at":"2025-06-14T20:01:52.106Z","avatar_url":"https://github.com/optuna.png","language":"Python","funding_links":[],"categories":["Data \u0026 Analytics","Ai Integration Mcp Servers","サーバー実装","Data Science Tools","📚 Projects (1974 total)","📦 Other"],"sub_categories":["AI/ML Platforms","💰 \u003ca name=\"finance--fintech\"\u003e\u003c/a\u003e金融・フィンテック","MCP Servers","How to Submit"],"readme":"# Optuna MCP Server\n\n[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue)](https://www.python.org)\n[![pypi](https://img.shields.io/pypi/v/optuna-mcp.svg)](https://pypi.python.org/pypi/optuna-mcp)\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/optuna/optuna-mcp)\n[![Tests](https://github.com/optuna/optuna-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/optuna/optuna-mcp/actions/workflows/tests.yml)\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that automates optimization and anlysis using [Optuna](http://optuna.org).\n\n\u003cimg width=\"840\" alt=\"image\" src=\"https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/sphere2d/images/sphere2d-6.png\" /\u003e\n\n## Use Cases\n\nThe Optuna MCP Server can be used in the following use cases, for example.\n\n- Automated hyperparameter optimization by LLMs\n- Interactive analysis of Optuna's optimization results via chat interface\n- Optimize input and output of other MCP tools\n\nFor details, see the [Examples section](#examples).\n\n## Installation\n\nThe Optuna MCP server can be installed using `uv` or Docker.\nThis section explains how to install the Optuna MCP server, using Claude Desktop as an example MCP client.\n\n### Usage with uv\n\nBefore starting the installation process, install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/).\n\nThen, add the Optuna MCP server configuration to the MCP client.\nTo include it in Claude Desktop, go to Claude \u003e Settings \u003e Developer \u003e Edit Config \u003e `claude_desktop_config.json`\nand add the following:\n\n```json\n{\n  \"mcpServers\": {\n    \"Optuna\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/optuna/optuna-mcp\",\n        \"optuna-mcp\"\n      ]\n    }\n  }\n}\n```\n\nAdditionally, you can specify the Optuna storage with the `--storage` argument to persist the results.\n\n```json\n{\n  \"mcpServers\": {\n    \"Optuna\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/optuna/optuna-mcp\",\n        \"optuna-mcp\"\n        \"--storage\",\n        \"sqlite:///optuna.db\"\n      ]\n    }\n  }\n}\n```\n\nAfter adding this, please restart Claude Desktop application.\nFor more information about Claude Desktop, check out [the quickstart page](https://modelcontextprotocol.io/quickstart/user).\n\n### Usage with Docker\n\nYou can also run the Optuna MCP server using Docker. Make sure you have Docker installed and running on your machine.\n\n```json\n{\n  \"mcpServers\": {\n    \"Optuna\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"--net=host\",\n        \"-v\",\n        \"/PATH/TO/LOCAL/DIRECTORY/WHICH/INCLUDES/DB/FILE:/app/workspace\",\n        \"optuna/optuna-mcp:latest\",\n        \"--storage\",\n        \"sqlite:////app/workspace/optuna.db\"\n      ],\n    }\n  }\n}\n```\n\n## Tools provided by Optuna MCP\n\nThe Optuna MCP provides the following tools.\nSpecifically, it offers primitive functions of Optuna such as Study, Trial, Visualization, and Dashboard.\nSince MCP clients know the list of tools and the details of each tool, users do not need to remember those details.\n\n### Study\n\n- **create_study** - Create a new Optuna study with the given study_name and directions.\n  If the study already exists, it will be simply loaded.\n  - `study_name` : name of the study (string, required).\n  - `directions`: The directions of optimization (list of literal strings minimize/maximize, optional).\n- **set_sampler** - Set the sampler for the study.\n  - `name` : the name of the sampler (string, required).\n- **get_all_study_names** - Get all study names from the storage.\n- **set_metric_names** - Set metric_names. Metric_names are labels used to distinguish what each objective value is.\n  - `metric_names` : The list of metric names for each objective (list of strings, required).\n- **get_metric_names** - Get metric_names.\n  - No parameters required.\n- **get_directions** - Get the directions of the study.\n  - No parameters required.\n- **get_trials** - Get all trials in a CSV format.\n  - No parameters required.\n- **best_trial** - Get the best trial.\n  - No parameters required.\n- **best_trials** - Return trials located at the Pareto front in the study.\n  - No parameters required.\n\n### Trial\n\n- **ask** - Suggest new parameters using Optuna.\n  - `search_space` : the search space for Optuna (dictionary, required).\n- **tell** - Report the result of a trial.\n  - `trial_number` : the trial number (integer, required).\n  - `values` : the result of the trial (float or list of floats, required).\n- **set_trial_user_attr** - Set user attributes for a trial.\n  - `trial_number`: the trial number (integer, required).\n  - `key`: the key of the user attribute (string, required).\n  - `value`: the value of the user attribute (any type, required).\n- **get_trial_user_attrs** - Get user attributes in a trial.\n  - `trial_number`: the trial number (integer, required).\n\n### Visualization\n\n- **plot_optimization_history** - Return the optimization history plot as an image.\n  - `target`: index to specify which value to display (integer, optional).\n  - `target_name`: target’s name to display on the axis label (string, optional).\n- **plot_hypervolume_history** - Return the hypervolume history plot as an image.\n  - `reference_point` : a list of reference points to calculate the hypervolume (list of floats, required).\n- **plot_pareto_front** - Return the Pareto front plot as an image for multi-objective optimization.\n  - `target_names`: objective name list used as the axis titles (list of strings, optional).\n  - `include_dominated_trials`: a flag to include all dominated trial's objective values (boolean, optional).\n  - `targets`: a list of indices to specify the objective values to display. (list of integers, optional).\n- **plot_contour** - Return the contour plot as an image.\n  - `params` : parameter list to visualize (list of strings, optional).\n  - `target` : an index to specify the value to display (integer, required).\n  - `target_name` : target’s name to display on the color bar (string, required).\n- **plot_parallel_coordinate** - Return the parallel coordinate plot as an image.\n  - `params` : parameter list to visualize (list of strings, optional).\n  - `target` : an index to specify the value to display (integer, required).\n  - `target_name` : target’s name to display on the axis label and the legend (string, required).\n- **plot_slice** - Return the slice plot as an image.\n  - `params` : parameter list to visualize (list of strings, optional).\n  - `target` : an index to specify the value to display (integer, required).\n  - `target_name` : target’s name to display on the axis label (string, required).\n- **plot_param_importances** - Return the parameter importances plot as an image.\n  - `params` : parameter list to visualize (list of strings, optional).\n  - `target` : an index to specify the value to display (integer/null, optional).\n  - `target_name` : target’s name to display on the legend (string, required).\n- **plot_edf** - Return the EDF plot as an image.\n  - `target` : an index to specify the value to display (integer, required).\n  - `target_name` : target’s name to display on the axis label (string, required).\n- **plot_timeline** - Return the timeline plot as an image.\n  - No parameters required.\n- **plot_rank** - Return the rank plot as an image.\n  - `params` : parameter list to visualize (list of strings, optional).\n  - `target` : an index to specify the value to display (integer, required).\n  - `target_name` : target’s name to display on the color bar (string, required).\n\n### Web Dashboard\n\n- **launch_optuna_dashboard** - Launch the Optuna dashboard.\n  - `port`: server port (integer, optional, default: 58080).\n\n## Examples\n\n- [Optimizing the 2D-Sphere function](#optimizing-the-2d-sphere-function)\n- [Starting the Optuna dashboard and analyzing optimization results](#starting-the-optuna-dashboard-and-analyzing-optimization-results)\n- [Optimizing the FFmpeg encoding parameters](#optimizing-the-ffmpeg-encoding-parameters)\n- [Optimizing the Cookie Recipe](#optimizing-the-cookie-recipe)\n\n### Optimizing the 2D-Sphere Function\n\nHere we present a simple example of optimizing the 2D-Sphere function, along with example prompts and the summary of the LLM responses.\n\n| User prompt | Output in Claude |\n| - | - |\n| (Launch Claude Desktop) | \u003cimg alt=\"1\" src=\"https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/sphere2d/images/sphere2d-1.png\" /\u003e |\n| Please create an Optuna study named \"Optimize-2D-Sphere\" for minimization. | \u003cimg alt=\"2\" src=\"https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/sphere2d/images/sphere2d-2.png\" /\u003e |\n| Please suggest two float parameters x, y in [-1, 1]. | \u003cimg alt=\"3\" src=\"https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/sphere2d/images/sphere2d-3.png\" /\u003e |\n| Please report the objective value x\\*\\*2 + y\\*\\*2. To calculate the value, please use the JavaScript interpreter and do not round the values. | \u003cimg alt=\"4\" src=\"https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/sphere2d/images/sphere2d-4.png\" /\u003e |\n| Please suggest another parameter set and evaluate it. | \u003cimg alt=\"5\" src=\"https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/sphere2d/images/sphere2d-5.png\" /\u003e |\n| Please plot the optimization history so far. | \u003cimg alt=\"6\" src=\"https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/sphere2d/images/sphere2d-6.png\" /\u003e |\n\n### Starting the Optuna Dashboard and Analyzing Optimization Results\n\nYou can also start the [Optuna dashboard](https://github.com/optuna/optuna-dashboard) via the MCP server to analyze the optimization results interactively.\n\n| User prompt | Output in Claude |\n| - | - |\n| Please launch the Optuna dashboard. | \u003cimg alt=\"7\" src=\"https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/optuna-dashboard/images/optuna-dashboard-1.png\" /\u003e |\n\nBy default, the Optuna dashboard will be launched on port 58080.\nYou can access it by navigating to `http://localhost:58080` in your web browser as shown below:\n\u003cimg alt=\"8\" src=\"https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/optuna-dashboard/images/optuna-dashboard-2.png\" /\u003e\n\nOptuna dashboard provides various visualizations to analyze the optimization results, such as optimization history, parameter importances, and more.\n\n### Optimizing the FFmpeg Encoding Parameters\n\n![ffmpeg-2](https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/ffmpeg/images/demo-ffmpeg-2.png)\n\nThis demo showcases how to use the Optuna MCP server to automatically find optimal FFmpeg encoding parameters. It optimizes x264 encoding options to maximize video quality (measured by the SSIM score) while keeping encoding time reasonable.\n\nCheck out [examples/ffmpeg.md](https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/ffmpeg/ffmpeg.md) for details.\n\n### Optimizing the Cookie Recipe\n\n![cookie-recipe](https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/cookie-recipe/images/result-table.png)\n\nIn this example, we will optimize a cookie recipe, referencing the paper titled \"[Bayesian Optimization for a Better Dessert](https://research.google/pubs/bayesian-optimization-for-a-better-dessert/)\".\n\nCheck out [examples/cookie-recipe](https://raw.githubusercontent.com/optuna/optuna-mcp/main/examples/cookie-recipe/README.md) for details.\n\n## License\n\nMIT License (see [LICENSE](./LICENSE)).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptuna%2Foptuna-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foptuna%2Foptuna-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptuna%2Foptuna-mcp/lists"}