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.

Related MCP server: my-mcp-server2

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-UI Inline Canvas & Local Drag-and-Drop: Direct in-chat canvas rendering via the MCP-UI / MCP Apps specification with local drag-and-drop file ingestion, eliminating external browser tabs and cloud attachment friction.

License

MIT License. See LICENSE for details.