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

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

# with uv
uv pip install pequod-mcp

# or with pip
pip install pequod-mcp

Run it directly (stdio):

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:

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.

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:

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

Claude Code:

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

Agent workflow examples

1. "What does SCHD actually hold?"

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?"

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 d

... View full README on GitHub