Scalene-MCP

A FastMCP v2 server providing LLMs with structured access to Scalene's comprehensive CPU, GPU, and memory profiling capabilities.

Installation

Prerequisites

• Python 3.10+

• uv (recommended) or pip

From Source

As a Package

Quick Start: Running the Server

Development Mode

Production Mode

🎯 Native Integration with VSCode LLM Editors

Works seamlessly with:

• ✅ GitHub Copilot - Direct integration

• ✅ Claude Code - VSCode extension

• ✅ Cursor - All-in-one IDE

• ✅ Any MCP-compatible LLM client

Zero-Friction Setup (3 Steps)

1. Install

   pip install scalene-mcp

2. Configure - Choose one method:

   Automated (Recommended):

   python scripts/setup_vscode.py

   Interactive setup script auto-finds your editor and configures it.

   Manual - GitHub Copilot:

   // .vscode/settings.json { "github.copilot.chat.mcp.servers": { "scalene": { "command": "uv", "args": ["run", "-m", "scalene_mcp.server"] } } }

   Manual - Claude Code / Cursor: See editor-specific setup guides

3. Restart VSCode/Cursor and start profiling!

Start Profiling Immediately

Open any Python project and ask your LLM:

The LLM automatically:

• 🔍 Detects your project structure

• 📄 Finds and profiles your code

• 📊 Analyzes CPU, memory, GPU usage

• 💡 Suggests optimizations

No path thinking. No manual configuration. Zero friction.

📚 Editor-Specific Setup:

• GitHub Copilot Setup

• Claude Code Setup

• Cursor Setup

📚 Full docs: SETUP_VSCODE.md | QUICKSTART.md | TOOLS_REFERENCE.md

Available Serving Methods (FastMCP)

Scalene-MCP can be served in multiple ways using FastMCP's built-in serving capabilities:

1. Standard Server (Default)

2. With Claude Desktop

Configure in your claude_desktop_config.json:

Then restart Claude Desktop.

3. With HTTP/SSE Endpoint

4. With Environment Variables

5. Programmatically

Programmatic Usage

Use Scalene-MCP directly in your Python code:

Overview

Scalene-MCP transforms Scalene's powerful profiling output into an LLM-friendly format through a clean, minimal set of well-designed tools. Get detailed performance insights without images or excessive context overhead.

What Scalene-MCP Does

• ✅ Profile Python scripts with full Scalene feature set

• ✅ Analyze profiles for hotspots, bottlenecks, memory leaks

• ✅ Compare profiles to detect regressions

• ✅ Pass arguments to profiled scripts

• ✅ Structured output in JSON format for LLMs

• ✅ Async execution for non-blocking profiling

What Scalene-MCP Doesn't Do

• ❌ In-process profiling (Scalene.start()/stop()) - uses subprocess instead for isolation

• ❌ Process attachment (--pid based profiling) - profiles scripts, not running processes

• ❌ Single-function profiling - designed for complete script analysis

Note: The subprocess-based approach was chosen for reliability and simplicity. LLM workflows typically profile complete scripts, which is a perfect fit. See SCALENE_MODES_ANALYSIS.md for detailed scope analysis.

Key Features

• Complete CPU profiling: Line-by-line Python/C time, system time, CPU utilization

• Memory profiling: Peak/average memory per line, leak detection with velocity metrics

• GPU profiling: NVIDIA and Apple GPU support with per-line attribution

• Advanced analysis: Stack traces, bottleneck identification, performance recommendations

• Profile comparison: Track performance changes across runs

• LLM-optimized: Structured JSON output, summaries before details, context-aware formatting

Available Tools (7 Consolidated Tools)

Scalene-MCP provides a clean, LLM-optimized set of 7 tools:

Discovery (3 tools)

• get_project_root() - Auto-detect project structure

• list_project_files(pattern, max_depth) - Find files by glob pattern

• set_project_context(project_root) - Override auto-detection

Profiling (1 unified tool)

• profile(type, script_path/code, ...) - Profile scripts or code snippets

  • type="script" for script profiling

  • type="code" for code snippet profiling

Analysis (1 mega tool)

• analyze(profile_id, metric_type, ...) - 9 analysis modes in one tool:

  • metric_type="all" - Comprehensive analysis

  • metric_type="cpu" - CPU hotspots

  • metric_type="memory" - Memory hotspots

  • metric_type="gpu" - GPU hotspots

  • metric_type="bottlenecks" - Performance bottlenecks

  • metric_type="leaks" - Memory leak detection

  • metric_type="file" - File-level metrics

  • metric_type="functions" - Function-level metrics

  • metric_type="recommendations" - Optimization suggestions

Comparison & Storage (2 tools)

• compare_profiles(before_id, after_id) - Compare two profiles

• list_profiles() - View all captured profiles

Full reference: See TOOLS_REFERENCE.md

Configuration

Profiling Options

The unified profile() tool supports these options:

Environment Variables

• SCALENE_CPU_PERCENT_THRESHOLD: Override default CPU threshold

• SCALENE_MALLOC_THRESHOLD: Override default malloc threshold

Architecture

Components

• ScaleneProfiler: Async wrapper around Scalene CLI

• ProfileParser: Converts Scalene JSON to structured models

• ProfileAnalyzer: Extracts insights and hotspots

• ProfileComparator: Compares profiles for regressions

• FastMCP Server: Exposes tools via MCP protocol

Data Flow

Troubleshooting

GPU Permission Error

If you see PermissionError when profiling with GPU:

Profile Not Found

Profiles are stored in memory during the server session. For persistence, implement the storage interface.

Timeout Issues

Adjust the timeout parameter (if using profiler directly):

Development

Running Tests

Code Quality

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Ensure all tests pass and coverage ≥ 85%

5. Submit a pull request

License

MIT License - see LICENSE file for details.

Citation

If you use Scalene-MCP in research, please cite both this project and Scalene:

Support

• Issues: GitHub Issues for bug reports and feature requests

• Discussions: GitHub Discussions for questions and ideas

• Documentation: See docs/ directory

Made with ❤️ for the Python performance community.

Manual Installation

Development

Prerequisites

• Python 3.10+

• uv (recommended) or pip

Setup

Project Structure

Usage

Running the Server

Example: Profile a Script

Example: Analyze Results

Testing

The project maintains 100% test coverage with comprehensive test suites:

Test fixtures include:

• Sample profiling scripts (fibonacci, memory-intensive, leaky)

• Realistic Scalene JSON outputs

• Edge cases and error conditions

Code Quality

This project follows strict code quality standards:

• Type Safety: 100% mypy strict mode compliance

• Linting: ruff with comprehensive rules

• Testing: 100% coverage requirement

• Style: Sleek-modern documentation, minimal functional emoji usage

• Patterns: FastMCP best practices throughout

Development Phases

Current Status: Phase 1.1 - Project Setup ✓

Documentation

Editor Setup Guides:

• GitHub Copilot Setup - Using Copilot Chat with VSCode

• Claude Code Setup - Using Claude Code VSCode extension

• Cursor Setup - Using the Cursor IDE

• General VSCode Setup - General VSCode configuration

API & Usage:

• Tools Reference - Complete API documentation (7 tools)

• Quick Start - 3-step setup and basic workflows

• Examples - Real-world profiling examples

Development Roadmap

1. Phase 1: Project Setup & Infrastructure ✓

2. Phase 2: Core Data Models (In Progress)

3. Phase 3: Profiler Integration

4. Phase 4: Analysis & Insights

5. Phase 5: Comparison Features

6. Phase 6: Resources Implementation

7. Phase 7: Prompts & Workflows

8. Phase 8: Testing & Quality

9. Phase 9: Documentation

10. Phase 10: Polish & Release

See development-plan.md for detailed roadmap.

Contributing

Contributions are welcome! Please ensure:

• All tests pass (just test)

• Linting passes (just lint)

• Type checking passes (just typecheck)

• Code coverage remains at 100%

License

[License TBD]

Links

• Scalene Profiler

• FastMCP Framework

• Model Context Protocol