pairbook-mcp
Officialpairbook-mcp
MCP server and CLI for PairBook, 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.
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
claude mcp add pairbook -- npx -y pairbook-mcpCursor: one-click install with
Claude Desktop: add this to claude_desktop_config.json:
{
"mcpServers": {
"pairbook": {
"command": "npx",
"args": ["-y", "pairbook-mcp"]
}
}
}Any other MCP client works the same way: run npx -y pairbook-mcp over stdio.
Related MCP server: TickerDB
Tools
Tool | What it answers |
| 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 |
| Correlation (1/3/5y, weekly), covariance, beta vs S&P 500, volatility and holdings overlap for two assets |
| One asset: beta, volatility, returns, most correlated assets |
| Lowest/most negative 3-year correlations to a given asset |
| Weekly return series (up to 156 weeks) for custom math |
| "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:
pairbook portfolio AAPL:25 MSFT:25 NVDA:20 JNJ:15 XOM:15RISK
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, invariants are covered by tests, and nothing is a forecast or advice.
CLI
The same data in your terminal, no install needed:
npx -y -p pairbook-mcp pairbook QQQ VOOor after npm i -g pairbook-mcp:
pairbook QQQ VOO # compare two assets
pairbook NVDA # one asset's profile
pairbook search nvidia # find a ticker
pairbook AAPL MSFT --jsonExit 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.
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: 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 with a DOI.
Free with attribution (a link back to 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.
License
MIT © VoidLab
Available Tools
6 toolsanalyze_portfolioAnalyze a portfolioARead-onlyIdempotent
Whole-portfolio risk and diversification analysis for 2 to 30 US stocks or ETFs: which positions are redundant, where the risk concentrates (Euler risk contributions), what actually diversifies, portfolio volatility, beta and market R2, diversification ratio, effective number of independent bets, correlation blocks that move together, max drawdown of the mix vs SPY, and issuer-sourced holdings-overlap warnings between the ETFs held. Use compare_pair for just two assets. Covers ~4,700 US-listed stocks and ETFs only (no crypto, no foreign listings, no inverse/leveraged short funds, no intraday data); figures use weekly closes and refresh once per trading day. Unknown tickers return an error: resolve them with resolve_symbol first.
Inputs: positions (required), detail. Returns: meta, flags, notes, terms, +7 more
compare_pairCompare two assetsARead-onlyIdempotent
Correlation (weekly returns), annualized covariance, beta vs S&P 500, volatility, max drawdown, calendar-year returns, fund facts (fees, yield, AUM) or stock fundamentals (market cap, P/E), and ETF holdings overlap with top common positions, for a pair of US stocks or ETFs. Popular pairs come from PairBook's precomputed matrix; any other pair of covered symbols is computed on demand from the weekly return series. Example: a=QQQ, b=VOO. Symbol order does not matter. Covers ~4,700 US-listed stocks and ETFs only (no crypto, no foreign listings, no inverse/leveraged short funds, no intraday data); figures use weekly closes and refresh once per trading day. Unknown tickers return an error: resolve them with resolve_symbol first.
Inputs: a (required), b (required). Returns: a, b, docs, fund, +13 more
find_diversifiersFind diversifiersARead-onlyIdempotent
Assets with the lowest or most negative 3-year correlation to the given US stock or ETF, each with its name and kind so you can screen them. Raw lowest-correlation list: it can contain leveraged/inverse ETNs, volatility products and illiquid micro-caps. Check name and kind before presenting anything as a portfolio diversifier. Covers ~4,700 US-listed stocks and ETFs only (no crypto, no foreign listings, no inverse/leveraged short funds, no intraday data); figures use weekly closes and refresh once per trading day. Unknown tickers return an error: resolve them with resolve_symbol first.
Inputs: symbol (required). Returns: docs, name, page, as_of, +4 more
resolve_symbolResolve a tickerARead-onlyIdempotent
Find the ticker for a company or fund name (e.g. 'nvidia' -> NVDA) across PairBook's ~4,700 covered US stocks and ETFs. Call this before other tools whenever the exact ticker is uncertain or a lookup returned not-found.
Inputs: query (required), limit. Returns: note, matches, total_matches
symbol_profileAsset profileARead-onlyIdempotent
One US stock or ETF: beta vs S&P 500, annualized volatility, 1/3/5-year returns, max drawdown, calendar-year returns, fund facts or stock fundamentals, and its most correlated assets. For diversification candidates use find_diversifiers. Covers ~4,700 US-listed stocks and ETFs only (no crypto, no foreign listings, no inverse/leveraged short funds, no intraday data); figures use weekly closes and refresh once per trading day. Unknown tickers return an error: resolve them with resolve_symbol first.
Inputs: symbol (required). Returns: docs, fund, kind, name, +13 more
weekly_returnsWeekly return seriesARead-onlyIdempotent
Weekly return series for one US stock or ETF (W-FRI, most recent last, all series end on the same Friday so tails align across symbols), for custom correlation or risk math. Covers ~4,700 US-listed stocks and ETFs only (no crypto, no foreign listings, no inverse/leveraged short funds, no intraday data); figures use weekly closes and refresh once per trading day. Unknown tickers return an error: resolve them with resolve_symbol first.
Inputs: symbol (required), weeks. Returns: docs, freq, as_of, terms, +3 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct level of analysis: single-symbol profile, pair comparison, portfolio analysis, raw return series, ticker resolution, and diversifier discovery. The only mild ambiguity is between compare_pair and analyze_portfolio for two-asset cases, but the descriptions explicitly state analyze_portfolio should be used for 2–30 assets and compare_pair for just two.
Tool names are uniformly lowercase and underscore-separated, and most follow verb_noun structure: compare_pair, find_diversifiers, resolve_symbol, analyze_portfolio. symbol_profile and weekly_returns break that pattern slightly by being noun phrases, but the naming remains predictable and readable.
Six tools is a well-scoped set for a financial analytics server: symbol resolution, single-asset profile, pair analysis, portfolio analysis, raw data access, and diversifier discovery each cover a distinct workflow without redundancy.
The core analytical workflows are well covered: resolving tickers, profiling a single asset, comparing pairs, finding diversifiers, fetching raw returns, and analyzing a full portfolio. Minor gaps remain, such as no bulk multi-symbol return/correlation endpoint or a standalone holdings-overlap tool, but agents can work around these with existing tools.
Maintenance
Related MCP Connectors
US ETF and mutual fund holdings, which ETFs hold a stock, overlap, look-through. Free, no API key.
Performance, risk, comparisons, backtests and screening for US stocks, ETFs and closed-end funds.
Stock quotes, charts, financials, options, SEC filings, crypto and macro data. Hosted, no API key.
Daily ML stock signals for 4,000+ US stocks, screening, company data and a portfolio optimizer.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides access to historical stock market data from US, UK, Russian, Turkish, and Hong Kong exchanges, including company profiles, market metrics, sector performance, rankings, and visualization data for financial analysis.9LGPL 3.0
- AlicenseAqualityBmaintenancePoint-in-time market data for AI agents: stocks, ETFs and crypto as named bands plus raw values.105MIT
- AlicenseAqualityBmaintenance63 deterministic quant computation tools for autonomous financial agents. Options pricing, derivatives, risk metrics, portfolio optimization, statistics, crypto/DeFi, macro/FX, time value of money. 1,000 free calls/day, no signup required.7414MIT
- AlicenseAqualityDmaintenancePortfolio risk analytics MCP server — VaR, Monte Carlo simulation, stress testing, portfolio optimization, options Greeks, and correlation analysis. Real market data via Yahoo Finance. Free tier available, Pro at $29/mo.102MIT