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

Tool	Purpose	Key Inputs
load_model	Load .joblib/.pkl model and configure explainer	model_path or model_url, model_type, background_path
run_analysis	Compute SHAP values over dataset	data_path or data_url or inline data, sample_size
get_feature_importance	Global ranking of top features	top_n (default 10)
explain_prediction	Local attribution breakdown for single instance	index or arbitrary data record
get_interaction	Pairwise feature interaction strength (Tree models)	feature_a, feature_b
get_plot	Render & save PNG visualisation with clickable URL	plot_type, index, feature_name, color_feature, top_n

---

Runtime Configuration

All runtime configuration is managed via environment variables:

Variable	Default	Description
SHAP_MCP_PORT	8765	HTTP server port (auto-increments if busy; --port flag overrides)
SHAP_MCP_API_KEY	(unset)	Bearer token for HTTP auth; unset = no auth required on localhost
SHAP_MCP_OUTPUT_DIR	./outputs/	Root directory for saving generated plot PNGs
SHAP_MCP_MAX_DOWNLOAD_MB	500	Maximum allowed size cap for URL-based model/dataset downloads
SHAP_MCP_LOG_LEVEL	INFO	Structured JSON log level (DEBUG, INFO, WARNING, ERROR)

---

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.