Metadata-Version: 2.4
Name: the13f-mcp
Version: 0.4.1
Summary: Model Context Protocol server for the13f - institutional 13F intelligence in Claude Desktop, Cursor, and VS Code.
Author-email: Pickel Fintech <tom@pickelfintech.com>
License-Expression: MIT
Project-URL: Homepage, https://the13f.com/integrations/
Project-URL: Documentation, https://the13f.com/integrations/mcp.html
Project-URL: Signup, https://the13f.com/integrations/
Project-URL: Source, https://github.com/pickelfintech/the13f-mcp
Project-URL: Changelog, https://github.com/pickelfintech/the13f-mcp/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/pickelfintech/the13f-mcp/issues
Keywords: 13f,sec,institutional,investment,mcp,claude,cursor,anthropic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.21.1
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.6
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# the13f-mcp

<!--
Official MCP Registry namespace claim. The registry reads this literal line
off the PyPI-hosted README to verify that whoever owns the `the13f-mcp`
PyPI package also claims the `com.the13f/mcp` namespace (DNS-verified via
a TXT record on the13f.com). Do not remove.
-->

mcp-name: com.the13f/mcp

> Model Context Protocol server for [the13f](https://the13f.com). Brings
> institutional 13F intelligence into Claude Desktop, Cursor, VS Code +
> Continue, and any MCP-compatible host — no HTTP code required on your side.

## Important limitations

Research data only. Sourced from publicly disclosed SEC Form 13F filings,
which lag quarter-end by up to 45 days. Past institutional positioning does
not predict future performance. Nothing here constitutes investment advice.
Every tool's response includes a `disclaimer` field; the host LLM should
surface it alongside any analysis it produces.

## Install

```
uvx the13f-mcp
```

Or `pip install the13f-mcp` if you prefer to manage Python environments
yourself. Python 3.11+ required.

## Get a free API key

Free, no payment, no credit card:

1. Visit <https://the13f.com/integrations/>
2. Enter your email and solve the Cloudflare Turnstile challenge
3. Copy your `pf13f_` key — **shown once**
4. Paste it into your MCP host's config as `THE13F_API_KEY` (see below)
5. Restart the host

Free tier: 100 read calls per day; quota rolls at UTC midnight. Signal and
report tools arrive in later minor versions when paid tiers launch.

## Configure your MCP host

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "the13f": {
      "command": "uvx",
      "args": ["the13f-mcp"],
      "env": {
        "THE13F_API_KEY": "pf13f_..."
      }
    }
  }
}
```

Restart Claude Desktop. The13f tools should appear in the MCP tool list.

### Cursor

Settings → MCP → Add Server. Paste the same JSON block into the "Custom"
field.

### VS Code with Continue

Settings → `experimental.modelContextProtocolServers` → add a `stdio`
transport running `uvx the13f-mcp` with `THE13F_API_KEY` in env. The key
reveal page at <https://the13f.com/integrations/signup-success> shows a
copy-paste-ready snippet with the key already filled in.

## Available tools — v0.2.0 (Read tier, free)

| Tool | What it does |
|------|---------------|
| `list_quarters` | All quarters with holdings data + the latest quarter |
| `search_managers` | Autocomplete 13F filers by name |
| `get_manager_holdings` | Full positions for a CIK + quarter |
| `get_manager_holdings_bulk` | Up to 25 `(cik, quarter)` pairs in one call |
| `list_all_managers` | Universe of 8,600+ filers with per-manager summary stats |
| `find_similar_managers` | Match a portfolio against the universe |
| `get_consensus_portfolio` | Most-widely-held securities per quarter |
| `get_market_regime` | Institutional regime snapshot (IIOI composite, state, transition) |
| `get_sector_flows` | Per-sector capital flows and risk posture |
| `get_manager_changes` | What a filer bought, sold, added and trimmed vs. the prior quarter |
| `get_security_ownership` | Which managers hold a stock, plus new buyers and exits |
| `get_manager_profile` | A filer's AUM + position-count history and a latest-quarter snapshot |
| `compare_managers` | Two managers head to head: shared positions, weight gaps, what's unique |

## Planned tools — later paid releases

| Tools | Requires |
|---|---|
| `get_security_signals`, `get_security_signals_bulk`, `get_portfolio_signals` | Paid tier subscription |
| `generate_manager_report`, `generate_security_report`, `generate_sector_report`, `check_report_status`, `wait_and_download_report` | Paid tier + stored card; two-step confirm |

The free-tier Read tools are enough to explore the data and build prompts
against it. Signal and report tools deliberately wait on the paid-tier
billing plumbing.

## Example prompts

> "Pull Berkshire Hathaway's top 20 positions as of Q4 2025 and summarize
> what grew the most quarter-over-quarter."

> "I own AAPL, MSFT, and NVDA equal-weight. Find the 5 institutional
> managers whose portfolios most closely resemble mine."

> "What sector did 13F filers most aggressively reduce last quarter? Show
> me the top three managers leading the reduction."

> "Which institutional managers hold NVDA this quarter, and who newly
> bought or exited it versus last quarter?"

> "What did Renaissance buy, sell, add, and trim last quarter, and where
> does its book overlap most with Two Sigma's?"

The MCP host's LLM picks the right tool, fills in arguments, surfaces the
`disclaimer`, and returns the result as structured JSON.

## Environment variables

| Var | Default | What it controls |
|---|---|---|
| `THE13F_API_KEY` | (none) | Your `pf13f_` key. Without it, tools return a structured "free signup required" response with a link to the signup page. |
| `THE13F_API_BASE_URL` | `https://api.the13f.com` | Override for local development against a running copy of the13f's gui_server. |
| `THE13F_MCP_TIMEOUT` | `30` | Per-request HTTP timeout in seconds. Minimum 5. |
| `THE13F_MCP_REPORTS` | `on` | `off` stops the server telling The 13F when it fails on your computer. A report carries the versions, your operating system, where it failed and the error message (see below). |

## When it fails on your computer

If the server fails to start, stops with an error or meets a bug of ours in a
tool, it sends The 13F one short report so we can fix it: this package's
version, the mcp library's and Python's versions, your operating system and
processor type, where in the package it failed and the error message with every
file path cut to its last part. It never sends your API key, your questions,
the data or a file path, and nothing leaves while it works. Set
`THE13F_MCP_REPORTS=off` to stop it.

## Source

Public source: <https://github.com/pickelfintech/the13f-mcp>. This is the
snapshot that PyPI, Glama.ai, and the MCP community list point at. The
GitHub repo is a push-mirror of the GitLab one at
`gitlab.com/pickel-fintech/the13f-mcp`; GitLab remains the primary and
also carries the release CI. Bug reports and PRs are accepted on either
side.

## License

MIT — see [`LICENSE`](./LICENSE). The hosted `api.the13f.com` API that this
client calls is a separate service. A free API key (100 calls/day) is
required; sign up at <https://the13f.com/integrations/>.

## Support

tom@pickelfintech.com — quote the `request_id` field returned by any failing
tool call for fastest triage.

## License

MIT. See [LICENSE](../LICENSE). The MCP server source is MIT-licensed; use
of the the13f API itself is governed by the Terms of Service at
<https://the13f.com/terms.html>.
