Pequod Mcp

io.github.ABWerksPublished by GitHub account ABWerksv0.2.2Updated Oct 24, 2026

Complete US ETF holdings from SEC N-PORT filings + ticker/CUSIP/FIGI crosswalk. Primary source.

VerifiedSTDIODesktop onlyFinanceData & Analytics

Overview

AI-generated overview

Read-only MCP server that returns complete US ETF holdings from SEC N-PORT filings and resolves tickers, CUSIPs, SEDOLs and FIGIs to symbols.

What you can do
It exposes five read-only tools: lookup_cik maps a ticker to an SEC CIK and entity metadata; resolve_ticker, resolve_cusip and resolve_figi turn raw identifiers into verified symbols; and get_etf_holdings returns a fund's complete holdings list from its latest monthly N-PORT filing, including name, ticker, ISIN, FIGI, LEI, shares, USD value, percentage of net assets, country and currency. Crosswalk results are cross-checked against SEC registry data and OpenFIGI, and a name mismatch vetoes the mapping instead of returning a wrong symbol. Holdings data comes from SEC EDGAR primary sources, with the filing URL included for citation.
When to use it
Use it when an assistant needs full ETF portfolio composition rather than a top-10 summary, or when identifiers from filings such as CUSIPs or FIGIs must be resolved to tradeable symbols. It also suits comparing overlap between funds, since two holdings calls can be joined on ISIN or ticker.
Requirements
A local Python environment with the pequod-mcp package installed via pip or uv, run over stdio. Network access to SEC EDGAR and OpenFIGI is needed. The optional API_OpenFIGI key raises OpenFIGI rate limits; the keyless tier works. Optional settings include PEQUOD_CACHE_DIR, PEQUOD_YAHOO_VERIFY and LOG_LEVEL.
Before you install
All tools are read-only and no credentials are required beyond the optional API_OpenFIGI key. Enabling the Yahoo enrichment extra sends requests to Yahoo and means accepting its terms of use. N-PORT holdings are published on a lag of roughly one to two months, so check report_date. Output is not investment advice and should be verified independently.

Installation

In SourceWeft

  1. Open Pequod Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

pequod-mcp — "the Gam"

SEC-primary-source ETF holdings + identifier crosswalk for agents.

An MCP (Model Context Protocol) server that gives AI agents the complete holdings of any US-registered ETF straight from SEC EDGAR N-PORT filings — not a top-10 scrape — plus a set of identifier-crosswalk tools (ticker, CUSIP/SEDOL, FIGI → resolved symbol) backed by OpenFIGI and SEC reference data. Runs locally over stdio; no vendor market-data subscriptions required.

Tools

ToolWhat it doesSources
lookup_cikTicker → SEC CIK + entity metadata (name, SIC, exchanges, fiscal year end)SEC company_tickers.json + submissions API
resolve_tickerRaw ticker + optional exchange code → Yahoo-convention symbol, verifiedExchange-suffix map (pure string mapping) + SEC + OpenFIGI
resolve_cusipCUSIP (or SEDOL) → symbol, with cross-source verificationOpenFIGI (one batched request) + SEC name/ticker agreement
resolve_figiBloomberg FIGI → symbol, with cross-source verificationOpenFIGI + SEC name/ticker agreement
get_etf_holdingsAny US ETF → complete holdings list from its latest monthly N-PORT filing (name, ticker, ISIN, FIGI, LEI, shares, USD value, % of net assets, country, currency)SEC EDGAR N-PORT XML

All tools are read-only.

How verification works

Crosswalk results are verified without any market-data vendor:

  1. SEC registry check — if the mapped ticker is a US SEC registrant, the entity title in company_tickers.json must agree with the OpenFIGI security name. A gross name mismatch vetoes the mapping (verification: "name_veto") rather than returning a plausible-looking wrong symbol.
  2. OpenFIGI mapping — non-US symbols (outside SEC's registry) verify on the OpenFIGI mapping itself, labeled verification: "openfigi" so you can tell the confidence tiers apart.

Yahoo Finance symbology (.SW, .T, .L, … suffixes) is applied as a pure string convention — the default path makes no network calls to Yahoo.

Install

bash
# with uvuv pip install pequod-mcp
# or with pippip install pequod-mcp

Run it directly (stdio):

bash
pequod-mcp

Optional: OpenFIGI API key

The server works without a key (OpenFIGI anonymous rate limits apply). For heavier use, get a free key at https://www.openfigi.com/api and set:

bash
export API_OpenFIGI="your-key-here"

Optional: Yahoo enrichment extra

An opt-in extra adds a live Yahoo quote block to crosswalk results. It is off by default and never used otherwise; enabling it means you accept the Yahoo Finance terms of use yourself.

bash
pip install 'pequod-mcp[yahoo]'export PEQUOD_YAHOO_VERIFY=1

Configure in Claude

Claude Desktop (claude_desktop_config.json) or any MCP client with a stdio transport:

json
{  "mcpServers": {    "pequod": {      "command": "pequod-mcp",      "env": {        "API_OpenFIGI": "your-key-here"      }    }  }}

Claude Code:

bash
claude mcp add pequod -e API_OpenFIGI=your-key-here -- pequod-mcp

Agent workflow examples

1. "What does SCHD actually hold?"

text
Agent: lookup_cik("SCHD")  → { cik: "0000884394", entity_name: "SCHWAB STRATEGIC TRUST", found: true }Agent: get_etf_holdings("SCHD", cik="0000884394")  → { fund_name, report_date, source_url (the actual EDGAR filing),      total_holdings: ~100, holdings: [ { name, ticker, isin, figi,      balance, value_usd, pct_val, ... } ] }

The agent gets every position with weights, plus the EDGAR URL for citation — auditable back to the primary source.

2. "I have a CUSIP from a 13F — what stock is this?"

text
Agent: resolve_cusip("594918104")  → { yahoo_symbol: "MSFT", verified: true, verification: "openfigi+sec",      company_name: "MICROSOFT CORP", cik: "0000789019",      openfigi: { figi: "BBG000BPH459", ... } }

If OpenFIGI's mapping disagrees with SEC's registry on who the ticker belongs to, the tool refuses (verification: "name_veto") instead of handing back a wrong symbol.

3. "Compare two dividend ETFs' overlap."

text
Agent: get_etf_holdings("SCHD")   → complete holdings AAgent: get_etf_holdings("VYM")    → complete holdings BAgent: joins on isin (or ticker), computes overlap weight, reports the       shared names — all from two tool calls, both citing SEC filings.

Data provenance

  • All holdings data comes from SEC EDGAR primary sources (Form N-PORT filings, the submissions API, and company_tickers.json). Identifier crosswalks come from the OpenFIGI API (FIGI is an open OMG standard).
  • No CUSIPs in output. Tool outputs carry ticker, ISIN, FIGI, and LEI; CUSIP fields present in the underlying filings are deliberately stripped.
  • SEC fair access respected: a declared User-Agent on every request, a throttle well under EDGAR's published rate limit, and an on-disk cache (.cache/ next to the module, override with PEQUOD_CACHE_DIR) for company_tickers.json (24 h) and N-PORT documents (30 days — filed documents are immutable).
  • Fail-loud policy: if EDGAR is unreachable or a filing cannot be parsed, tools return an error. There is no degraded or partial fallback source — you either get filing-backed data or a clear failure.
  • N-PORT filings are published on a lag (holdings are typically ~1–2 months behind). The report_date and source_url fields tell you exactly which period you are looking at.
  • Not investment advice. This server relays public regulatory filings and open identifier mappings; verify independently before making investment decisions.

Environment variables

VariableDefaultPurpose
API_OpenFIGI(unset)OpenFIGI API key (higher rate limits)
PEQUOD_CACHE_DIR.cache/ next to the moduleOn-disk cache location
PEQUOD_YAHOO_VERIFY(off)Opt-in Yahoo enrichment (needs the [yahoo] extra)
LOG_LEVELINFOServer log verbosity

Development

bash
pip install -e '.[dev]'pytest            # fully offline — fixture filings, no live network

License

Apache-2.0 — see LICENSE. Copyright 2026 AB Evergreen Analytics LLC.

Source: README.md at commit 4589604

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts