# pairbook-mcp

[![npm](https://img.shields.io/npm/v/pairbook-mcp)](https://www.npmjs.com/package/pairbook-mcp) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/vj88-coder/pairbook-mcp)

MCP server and CLI for [PairBook](https://www.pairbook.io), the correlation and ETF-overlap engine covering 4,700+ US stocks and ETFs. Any of the 11.3 million possible pairs can be compared: 52,000+ popular pairs come precomputed with issuer-sourced holdings overlap, and every other combination is computed on demand from weekly return series. The underlying JSON API is free and static, needs no key, and refreshes every trading day after the US close.

<p align="center"><img src=".github/demo.svg" alt="pairbook portfolio finding that QQQ, QQQM and VOO are a single bet" width="760"></p>

Ask your AI assistant things like *"is my portfolio too concentrated?"*, *"how correlated are QQQ and VOO, and how much do they overlap?"* or *"find me diversifiers for NVDA"* and it can answer with fresh, sourced numbers instead of guessing.

## MCP setup

**Claude Code**

```bash
claude mcp add pairbook -- npx -y pairbook-mcp
```

**Cursor**: one-click install with [![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-black)](cursor://anysphere.cursor-deeplink/mcp/install?name=pairbook&config=eyJjb21tYW5kIjogIm5weCIsICJhcmdzIjogWyIteSIsICJwYWlyYm9vay1tY3AiXX0=)

**Claude Desktop**: add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pairbook": {
      "command": "npx",
      "args": ["-y", "pairbook-mcp"]
    }
  }
}
```

Any other MCP client works the same way: run `npx -y pairbook-mcp` over stdio.

## Tools

| Tool | What it answers |
|---|---|
| `analyze_portfolio` | Whole portfolio (2 to 30 positions): Euler risk contributions, diversification ratio and independent risk bets, correlation blocks, drawdown vs SPY, ETF-overlap warnings between held funds |
| `compare_pair` | Correlation (1/3/5y, weekly), covariance, beta vs S&P 500, volatility and holdings overlap for two assets |
| `symbol_profile` | One asset: beta, volatility, returns, most correlated assets |
| `find_diversifiers` | Lowest/most negative 3-year correlations to a given asset |
| `weekly_returns` | Weekly return series (up to 156 weeks) for custom math |
| `resolve_symbol` | "nvidia" → NVDA across the covered universe |

## Portfolio analysis

Give it a whole portfolio (2 to 30 positions, weights optional) and it tells you which positions are redundant, where the risk concentrates, what actually diversifies, and whether the ETFs you hold overlap under the hood:

```bash
pairbook portfolio AAPL:25 MSFT:25 NVDA:20 JNJ:15 XOM:15
```

```text
RISK
  volatility     16.7%  (weighted average of the parts: 29.0%)
  beta vs SPY    0.99    market explains 73% of the moves (R2)
  max drawdown   -17.4%  (2024-12-05 to 2025-04-03, SPY: -16.9%)

RISK BUDGET  (share of portfolio risk vs share of capital)
  NVDA   ############  43.1% risk     20% capital  beta 2.18  risk engine  <- 20% of the capital but 43% of the risk
  AAPL   ########      27.1% risk     25% capital  beta 1.06  diversifier
  ...
```

The MCP tool `analyze_portfolio` returns the same analysis as structured JSON: Euler risk contributions, diversification ratio and independent risk bets, correlation blocks that move together, drawdown vs SPY, and issuer-sourced overlap warnings between the ETFs held (QQQ and VOO holding 53.5% of the same stocks is something no other portfolio tool reports). Every formula is documented in [docs/methodology.md](docs/methodology.md), invariants are covered by tests, and nothing is a forecast or advice.

## CLI

The same data in your terminal, no install needed:

```bash
npx -y -p pairbook-mcp pairbook QQQ VOO
```

or after `npm i -g pairbook-mcp`:

```bash
pairbook QQQ VOO         # compare two assets
pairbook NVDA            # one asset's profile
pairbook search nvidia   # find a ticker
pairbook AAPL MSFT --json
```

Exit codes: 0 on success, 1 on any error (errors go to stderr). `--json` prints one valid JSON document on stdout, so `pairbook qqq voo --json | jq .correlation_weekly` just works.

```text
DGRO vs SCHD  (data as of 2026-08-27)
  correlation   1y 0.74   3y 0.88   5y 0.93
  beta vs SPY   DGRO 0.65   SCHD 0.52
  volatility    DGRO 11.4%   SCHD 12.9%
  overlap       20.8% across 32 common holdings (issuer files 2026-08-26)
  https://www.pairbook.io/pair/dgro-vs-schd/
```

## Scope

PairBook is a specialist: correlation, overlap and diversification structure. It pairs well with a general market-data MCP server that brings quotes, fundamentals and news, so install both and let your assistant combine them.

## Data

Everything comes from the free [PairBook API](https://www.pairbook.io/api/): correlations computed on weekly returns (1/3/5-year windows), overlap from issuer portfolio disclosures, recomputed every trading day. The dataset is also published as [CSV downloads](https://www.pairbook.io/data/) with a DOI.

Free with attribution (a link back to [pairbook.io](https://www.pairbook.io)). US-listed stocks and ETFs only. **Nothing here is investment advice.**

## Privacy

The server and CLI run entirely on your machine and are read-only. They call a single host (www.pairbook.io) to fetch public market data, identify themselves with a version and surface string in the user agent, and send nothing else: no prompts, no conversation content, no personal data, no telemetry. Full policy: [pairbook.io/privacy](https://www.pairbook.io/privacy/).

## License

[MIT](LICENSE) © VoidLab