Scalene-MCP Server

Provides MCP-backed access to Scalene’s profiling features for Python scripts with structured JSON outputs.

python

1

GitHub Stars

python

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "ptmorris05-scalene-mcp": {
      "command": "python",
      "args": [
        "-m",
        "scalene_mcp.server"
      ],
      "env": {
        "SCALENE_TIMEOUT": "30",
        "SCALENE_PYTHON_EXECUTABLE": "python (or specific interpreter)"
      }
    }
  }
}

Scalene-MCP is a FastMCP v2 server that exposes Scalene’s CPU, memory, and GPU profiling capabilities to LLMs in a structured, JSON-friendly form. It lets you profile entire Python scripts and provides analysis, comparisons, and optimization suggestions that you can integrate into your AI-assisted development workflows.

How to use

You use Scalene-MCP by running the server locally and connecting an MCP client to it. You can profile Python scripts or code snippets, request detailed analyses, and obtain structured output that is easy for an LLM to consume. Start the server in development mode to iterate quickly, or run it in production mode for longer sessions. Your client can invoke the profiling tool, request analyses, and compare profiles to detect regressions or bottlenecks.

How to install

Prerequisites: install Python 3.10 or newer. You can use uv as the preferred runner or fall back to pip.

# From Source
git clone https://github.com/plasma-umass/scalene-mcp.git
cd scalene-mcp
uv venv
uv sync

# Or install as a package
pip install scalene-mcp

Additional setup after install

Start the server in development mode to profile locally with auto-reload or quick iterations. You can also run it in production mode when you are ready for deployment.

# Development mode with uv
uv run scalene_mcp.server

# Development mode with python -m
python -m scalene_mcp.server

# Production mode
python -m scalene_mcp.server

Configuration and environment

Configure runtime behavior using environment variables to tailor profiling thresholds and timeouts.

export SCALENE_CPU_PERCENT_THRESHOLD=1.0
export SCALENE_MALLOC_THRESHOLD=100
python -m scalene_mcp.server

Notes on integration with MCP clients

The server exposes tools via the MCP protocol and can be accessed by any MCP-compatible client. Use the standard start commands shown above and connect your MCP client to the running server using the appropriate channel (stdio or HTTP/SSE if configured).

Available tools

get_project_root

Auto-detects the project root to understand the workspace layout and locate relevant files for profiling.

list_project_files

Find files in the project matching a glob pattern up to a maximum directory depth.

set_project_context

Override automatic project detection to lock in a specific root for profiling.

profile

Unified profiling tool to run Scalene on a script or code snippet with configurable options for memory and GPU profiling.

analyze

Single mega-tool with multiple analysis modes to surface CPU hotspots, memory issues, GPU usage, bottlenecks, leaks, and optimization recommendations.

compare_profiles

Compare two profiling results to identify regressions or improvements.

list_profiles

List all captured profiling results stored in the session.