SwanLab MCP Server

A Model Context Protocol (MCP) server implementation for SwanLab, combining SwanLab-OpenAPI & FastMCP.

✨ Features

Core Features

• Workspace Queries - List accessible workspaces and enumerate workspace projects

• Project Queries - List projects and inspect a specific project with run summaries

• Run Queries - Inspect runs with normalized fields (id, state, profile, user)

• Metric Queries - Fetch metric tables with consistent columns, rows, and total

• API Integration - Provide read-only access through SwanLab OpenAPI (swanlab.Api)

Tech Stack

• Language: Python 3.12+

• Core Framework: FastMCP (v2.14.4+)

• API Client: SwanLab SDK

• Config Management: Pydantic Settings

🚀 Quick Start

❗️Configuration

Add the following configuration to your relative mcp config list

{
  "mcpServers": 
    ...
    {
    "swanlab-mcp": {
      "command": "uvx",
      "args": ["--from", "swanlab-mcp", "swanlab_mcp", "--transport", "stdio"],
      "env": {
        "SWANLAB_API_KEY": "your_api_key_here"
      }
    }
  }
}

For Claude Code Users, you can config like this:

claude mcp add --env SWANLAB_API_KEY=<your_api_key> -- swanlab_mcp uvx --from swanlab-mcp swanlab_mcp --transport stdio

Prerequisites

• Python >= 3.12

• SwanLab API Key (get it from SwanLab)

Installation

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

Configuration

Environment Variables

Create a .env file and configure your API key:

cp .env.template .env

Edit the .env file:

SWANLAB_API_KEY=your_api_key_here

Running

# Using stdio transport (default)
python -m swanlab_mcp

# Or using CLI
python -m swanlab_mcp --transport stdio

# Check version
python -m swanlab_mcp --version

Usage

After configuration, restart Claude Desktop to interact with SwanLab via the MCP protocol.

Available Tools:

• swanlab_list_workspaces - List workspaces

• swanlab_get_workspace - Get workspace details

• swanlab_list_projects_in_workspace - List projects in one workspace

• swanlab_list_projects - List projects

• swanlab_get_project - Get project details

• swanlab_list_runs_in_project - List runs in one project

• swanlab_list_runs - List runs with optional filters (state, config.*)

• swanlab_get_run - Get run details

• swanlab_get_run_config - Get run config

• swanlab_get_run_metadata - Get run metadata

• swanlab_get_run_requirements - Get run requirements

• swanlab_list_run_metric_keys - List available metric keys for a run

• swanlab_get_run_metrics - Get run metric table

Resource Definitions:

• workspace: collection of projects (PERSON or TEAM) identified by username.

• project: collection of runs identified by path = username/project_name.

• run: single experiment identified by path = username/project_name/experiment_id.

• metric: tabular run history returned as {path, keys, x_axis, sample, columns, rows, total}.

🛠️ Development

Code Formatting

# Using Makefile
make format

# Or manually
uvx isort . --skip-gitignore
uvx ruff format . --quiet

Lint Check

uvx ruff check .

Pre-commit Hooks

bash scripts/install-hooks.sh

📚 References & Acknowledgements

• SwanLab

• Model Context Protocol

• FastMCP v2

• modelscope-mcp-server

• TrackIO-mcp-server

• Simple-Wandb-mcp-server

📄 License

MIT License