{
  "markdown": "# pequod-mcp — \"the Gam\"\n<!-- mcp-name: io.github.ABWerks/pequod-mcp -->\n\n**SEC-primary-source ETF holdings + identifier crosswalk for agents.**\n\nAn MCP (Model Context Protocol) server that gives AI agents the *complete*\nholdings of any US-registered ETF straight from SEC EDGAR N-PORT filings —\nnot a top-10 scrape — plus a set of identifier-crosswalk tools (ticker,\nCUSIP/SEDOL, FIGI → resolved symbol) backed by OpenFIGI and SEC reference\ndata. Runs locally over stdio; no vendor market-data subscriptions required.\n\n## Tools\n\n| Tool | What it does | Sources |\n|---|---|---|\n| `lookup_cik` | Ticker → SEC CIK + entity metadata (name, SIC, exchanges, fiscal year end) | SEC `company_tickers.json` + submissions API |\n| `resolve_ticker` | Raw ticker + optional exchange code → Yahoo-convention symbol, verified | Exchange-suffix map (pure string mapping) + SEC + OpenFIGI |\n| `resolve_cusip` | CUSIP (or SEDOL) → symbol, with cross-source verification | OpenFIGI (one batched request) + SEC name/ticker agreement |\n| `resolve_figi` | Bloomberg FIGI → symbol, with cross-source verification | OpenFIGI + SEC name/ticker agreement |\n| `get_etf_holdings` | Any 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 |\n\nAll tools are read-only.\n\n### How verification works\n\nCrosswalk results are verified without any market-data vendor:\n\n1. **SEC registry check** — if the mapped ticker is a US SEC registrant, the\n   entity title in `company_tickers.json` must agree with the OpenFIGI\n   security name. A gross name mismatch **vetoes** the mapping\n   (`verification: \"name_veto\"`) rather than returning a plausible-looking\n   wrong symbol.\n2. **OpenFIGI mapping** — non-US symbols (outside SEC's registry) verify on\n   the OpenFIGI mapping itself, labeled `verification: \"openfigi\"` so you\n   can tell the confidence tiers apart.\n\nYahoo Finance *symbology* (`.SW`, `.T`, `.L`, … suffixes) is applied as a\npure string convention — the default path makes **no network calls to\nYahoo**.\n\n## Install\n\n```bash\n# with uv\nuv pip install pequod-mcp\n\n# or with pip\npip install pequod-mcp\n```\n\nRun it directly (stdio):\n\n```bash\npequod-mcp\n```\n\n### Optional: OpenFIGI API key\n\nThe server works without a key (OpenFIGI anonymous rate limits apply). For\nheavier use, get a free key at <https://www.openfigi.com/api> and set:\n\n```bash\nexport API_OpenFIGI=\"your-key-here\"\n```\n\n### Optional: Yahoo enrichment extra\n\nAn opt-in extra adds a live Yahoo quote block to crosswalk results. It is\n**off by default** and never used otherwise; enabling it means you accept\nthe Yahoo Finance terms of use yourself.\n\n```bash\npip install 'pequod-mcp[yahoo]'\nexport PEQUOD_YAHOO_VERIFY=1\n```\n\n## Configure in Claude\n\n**Claude Desktop** (`claude_desktop_config.json`) or any MCP client with a\nstdio transport:\n\n```json\n{\n  \"mcpServers\": {\n    \"pequod\": {\n      \"command\": \"pequod-mcp\",\n      \"env\": {\n        \"API_OpenFIGI\": \"your-key-here\"\n      }\n    }\n  }\n}\n```\n\n**Claude Code:**\n\n```bash\nclaude mcp add pequod -e API_OpenFIGI=your-key-here -- pequod-mcp\n```\n\n## Agent workflow examples\n\n**1. \"What does SCHD actually hold?\"**\n\n```text\nAgent: lookup_cik(\"SCHD\")\n  → { cik: \"0000884394\", entity_name: \"SCHWAB STRATEGIC TRUST\", found: true }\nAgent: get_etf_holdings(\"SCHD\", cik=\"0000884394\")\n  → { fund_name, report_date, source_url (the actual EDGAR filing),\n      total_holdings: ~100, holdings: [ { name, ticker, isin, figi,\n      balance, value_usd, pct_val, ... } ] }\n```\n\nThe agent gets every position with weights, plus the EDGAR URL for citation\n— auditable back to the primary source.\n\n**2. \"I have a CUSIP from a 13F — what stock is this?\"**\n\n```text\nAgent: resolve_cusip(\"594918104\")\n  → { yahoo_symbol: \"MSFT\", verified: true, verification: \"openfigi+sec\",\n      company_name: \"MICROSOFT CORP\", cik: \"0000789019\",\n      openfigi: { figi: \"BBG000BPH459\", ... } }\n```\n\nIf OpenFIGI's mapping disagrees with SEC's registry on who the ticker\nbelongs to, the tool refuses (`verification: \"name_veto\"`) instead of\nhanding back a wrong symbol.\n\n**3. \"Compare two dividend ETFs' overlap.\"**\n\n```text\nAgent: get_etf_holdings(\"SCHD\")   → complete holdings A\nAgent: get_etf_holdings(\"VYM\")    → complete holdings B\nAgent: joins on isin (or ticker), computes overlap weight, reports the\n       shared names — all from two tool calls, both citing SEC filings.\n```\n\n## Data provenance\n\n- **All holdings data comes from SEC EDGAR primary sources** (Form N-PORT\n  filings, the submissions API, and `company_tickers.json`). Identifier\n  crosswalks come from the **OpenFIGI API** (FIGI is an open OMG standard).\n- **No CUSIPs in output.** Tool outputs carry ticker, ISIN, FIGI, and LEI;\n  CUSIP fields present in the underlying filings are deliberately stripped.\n- **SEC fair access respected:** a declared User-Agent on every request, a\n  throttle well under EDGAR's published rate limit, and an on-disk cache\n  (`.cache/` next to the module, override with `PEQUOD_CACHE_DIR`) for\n  `company_tickers.json` (24 h) and N-PORT documents (30 days — filed\n  documents are immutable).\n- **Fail-loud policy:** if EDGAR is unreachable or a filing cannot be\n  parsed, tools return an error. There is no degraded or partial fallback\n  source — you either get filing-backed data or a clear failure.\n- N-PORT filings are published on a lag (holdings are typically ~1–2 months\n  behind). The `report_date` and `source_url` fields tell you exactly which\n  period you are looking at.\n- **Not investment advice.** This server relays public regulatory filings\n  and open identifier mappings; verify independently before making\n  investment decisions.\n\n## Environment variables\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `API_OpenFIGI` | *(unset)* | OpenFIGI API key (higher rate limits) |\n| `PEQUOD_CACHE_DIR` | `.cache/` next to the module | On-disk cache location |\n| `PEQUOD_YAHOO_VERIFY` | *(off)* | Opt-in Yahoo enrichment (needs the `[yahoo]` extra) |\n| `LOG_LEVEL` | `INFO` | Server log verbosity |\n\n## Development\n\n```bash\npip install -e '.[dev]'\npytest            # fully offline — fixture filings, no live network\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE). Copyright 2026 AB Evergreen Analytics LLC.\n",
  "bytes": 6303,
  "sha": "369c8f0979f80c91200c3e81e19bc998c286255fdc27928ae17271ec008846f3",
  "repo_slug": "abwerks/pequod-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_abwerks_pequod_mcp_e9964c77/readme"
}