SHAP MCP Server (shap-mcp)

A lightweight, focused Model Context Protocol (MCP) server that exposes SHAP (SHapley Additive exPlanations) model explainability as agent-callable tools.

Designed for AI assistants (like Claude Desktop) and human data scientists to collaborate seamlessly across a shared in-memory session.

Key Features

• Dual Simultaneous Transports: Standard stdio transport for Claude Desktop alongside a Starlette HTTP transport on port 8765 serving the Web GUI and generated visualisations.
• Unified In-Memory Session: Run analysis via the Web GUI and ask questions in Claude, or have Claude trigger analysis and view generated plots instantly in the GUI gallery.
• Universal Model Support:
  • tree: Exact TreeExplainer for XGBoost, LightGBM, CatBoost, RandomForest, ExtraTrees.
  • linear: Fast closed-form LinearExplainer for Logistic Regression, Ridge, Lasso.
  • deep: DeepExplainer for PyTorch neural networks.
  • kernel: Model-agnostic KernelExplainer with automatic kmeans clustering.
• Publication-Ready Visualisations: Generate and save 6 plot types (summary, bar, waterfall, force, dependence, heatmap) with pre-formatted clickable browser and local file links.
• URL & File Ingestion: Ingest models and CSV datasets from local paths or public HTTP/HTTPS URLs with streaming downloads, automatic size caps (SHAP_MCP_MAX_DOWNLOAD_MB), and temp-file cleanup.
• Security: Optional API key authentication via SHAP_MCP_API_KEY for HTTP endpoints.

Installation

# Standard installation
pip install shap-mcp

# Optional extra for PyTorch DeepExplainer support
pip install shap-mcp[deep]

Claude Desktop Configuration

Add shap-mcp to your claude_desktop_config.json:

Universal Recommended Setup (via uvx)

{
  "mcpServers": {
    "shap-mcp": {
      "command": "uvx",
      "args": ["shap-mcp", "--no-ui"]
    }
  }
}

Direct Pip / Pipx Setup

{
  "mcpServers": {
    "shap-mcp": {
      "command": "shap-mcp",
      "args": ["--no-ui"]
    }
  }
}

Tool Reference

Runtime Configuration

All runtime configuration is managed via environment variables:

Web GUI

When started directly via shap-mcp, the server automatically opens the Web GUI at http://localhost:8765/ui/:

• Configuration Form: Input local paths or URLs, pick model architecture, and run analysis.
• Real-Time Badges: Live model loaded status, rows analyzed count, and active explainer type.
• Dynamic Plot Gallery: Thumbnails appear automatically as Claude or the GUI generates visualisations.
• Instance Explainer: Interactive table of individual feature contributions.

Upcoming Features & Roadmap

The following capabilities are planned for upcoming releases:

• save_analysis / load_analysis: Serialize computed SHAP values to .npz files to skip re-computation on reload and share results across teams.
• Auth-Protected Remote Ingestion: Support for Hugging Face tokens, private S3/GCS buckets, and presigned URLs.
• Tabbed GUI & Progressive Disclosure: Redesign the Web GUI into clean, focused tabs with progressive unlocking as analysis completes.
• Interactive Visualisations: Pan, zoom, and tooltip hover support on matplotlib charts via mpld3.
• Plot-Specific Guided Prompts: Dedicated MCP prompts tailored for each of the 6 visualization types.
• Multi-Tenant Session Isolation: Connection-isolated session states for shared multi-user server deployments.
• Additional Model Formats: Native support for ONNX runtime, MLflow models, and Weights & Biases model registries.
• Fairness & Bias Disaggregation: Per-subgroup demographic parity and slice-based SHAP analysis.
• MCP Inline UI / Canvases: Direct inline rendering within supported MCP host clients.

License

MIT License. See LICENSE for details.