# Shadowjoin

> Shadowjoin is an open-source MCP server for analytics and data. Local MCP server that measures how many matches an exact join silently drops. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/harsh-chandak/shadowjoin
- **MCP Registry name:** io.github.harsh-chandak/shadowjoin
- **Categories:** [analytics and data](https://ai-powered.com/categories/analytics-and-data)
- **Listing updated:** 2026-11-18

## About

Joining two sources on a name, email or SKU quietly loses rows that differ only by punctuation, suffixes or word order. Shadowjoin runs a shadow matcher beside the real key, reports a lower bound on lost matches, and names the normalization rules that would recover them, in order of marginal gain. When you supply a ground-truth column it also checks whether the recoveries are right.

The README's worked examples include S&P 500 names against exchange listings, where an exact join found 1 match and the shadow join recovered 428, with 99.76% precision on verified rows. It also shows that applying every rule can recover nothing while a two-rule subset recovers five, and it separates mechanical misses from semantic ones such as Cape Verde versus Cabo Verde that need an alias table. Multi-column keys report which component disagreed.

It runs over stdio from npm with no postinstall script. SHADOWJOIN_CONFIG must point to a config file naming your data sources; connection strings stay in that file and never pass through a tool call.

## Features

- **Lost-match floor:** Report a lower bound on matches an exact join misses.
- **Ranked rules:** List normalization rules in order of marginal recovery.
- **Ground-truth checking:** Verify recoveries with a truth column and report precision.
- **Multi-column keys:** Show which key component disagreed on missed rows.
- **Mechanical vs semantic misses:** Separate fixable string issues from ones needing entity resolution.
- **Safe install:** No postinstall script; credentials stay in a config file.

## Good for

- Audit a customer-to-CRM join before trusting a dashboard
- Find which cleaning rules to add to a pipeline
- Check a country-name join against ISO codes
- Decide whether misses need an alias table

## Install

### Claude Code (Terminal)

```sh
claude mcp add shadowjoin --env SHADOWJOIN_CONFIG='<SHADOWJOIN_CONFIG>' -- npx -y shadowjoin
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "shadowjoin": {
      "command": "npx",
      "args": [
        "-y",
        "shadowjoin"
      ],
      "env": {
        "SHADOWJOIN_CONFIG": "<SHADOWJOIN_CONFIG>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "shadowjoin": {
      "command": "npx",
      "args": [
        "-y",
        "shadowjoin"
      ],
      "env": {
        "SHADOWJOIN_CONFIG": "<SHADOWJOIN_CONFIG>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "shadowjoin": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "shadowjoin"
      ],
      "env": {
        "SHADOWJOIN_CONFIG": "<SHADOWJOIN_CONFIG>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "shadowjoin": {
      "command": "npx",
      "args": [
        "-y",
        "shadowjoin"
      ],
      "env": {
        "SHADOWJOIN_CONFIG": "<SHADOWJOIN_CONFIG>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "shadowjoin": {
      "command": "npx",
      "args": [
        "-y",
        "shadowjoin"
      ],
      "env": {
        "SHADOWJOIN_CONFIG": "<SHADOWJOIN_CONFIG>"
      }
    }
  }
}
```

## FAQ

### Does it change my data?

The README describes measurement only: it reports lost matches and suggested rules.

### Where do connection strings go?

In the file named by SHADOWJOIN_CONFIG, never in a tool call.

### Does it run install scripts?

No, the README says there is no postinstall script.

### Can I run it without MCP?

Yes, the README shows a CLI: npx shadowjoin scan with left and right sources and keys.

### Is Shadowjoin free?

Yes. Shadowjoin is open source, so you can use and self-host it for free.

### How do I add Shadowjoin to Claude Code?

Run this command in your terminal: claude mcp add shadowjoin --env SHADOWJOIN_CONFIG='<SHADOWJOIN_CONFIG>' -- npx -y shadowjoin

### What are the best alternatives to Shadowjoin?

The closest alternatives to Shadowjoin are Agent-Native Analytics, Google Ads + Meta Ads + SEO/GEO MCP, dashboard-icons, Tapetide - Indian Stock Market MCP and World Monitor.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Agent-Native Analytics](https://ai-powered.com/mcp/agent-native-analytics): Agent-Native Analytics is an open-source MCP server for analytics and data.
- [Google Ads + Meta Ads + SEO/GEO MCP](https://ai-powered.com/mcp/google-ads-meta-ads-seo-geo-mcp): Google Ads + Meta Ads + SEO/GEO MCP is a freemium MCP server for marketing and seo.
- [dashboard-icons](https://ai-powered.com/mcp/dashboard-icons): dashboard-icons is an open-source MCP server for analytics and data.
- [Tapetide - Indian Stock Market MCP](https://ai-powered.com/mcp/tapetide-indian-stock-market-mcp): Tapetide - Indian Stock Market MCP is a freemium MCP server for finance and payments.
- [World Monitor](https://ai-powered.com/mcp/world-monitor): World Monitor is a freemium MCP server for analytics and data.
- [DataArcus for Power BI](https://ai-powered.com/mcp/dataarcus-for-power-bi): DataArcus for Power BI is a free MCP server for analytics and data.
- [CompanyData](https://ai-powered.com/mcp/companydata): CompanyData is a paid MCP server for analytics and data.
- [Pypi Stats](https://ai-powered.com/mcp/pypi-stats): Pypi Stats is a freemium MCP server for analytics and data.

---
Source: https://ai-powered.com/mcp/shadowjoin
