Metadata-Version: 2.4
Name: the13f-mcp
Version: 0.1.2
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/developers/
Project-URL: Documentation, https://the13f.com/developers/mcp.html
Project-URL: Signup, https://the13f.com/developers/
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>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=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

> 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/developers/>
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/developers/signup-success> shows a
copy-paste-ready snippet with the key already filled in.

## Available tools — v0.1.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 |

## Planned tools — later versions

| Version | Tools | Requires |
|---|---|---|
| v0.2.0 | `get_security_signals`, `get_security_signals_bulk`, `get_portfolio_signals` | Standard tier subscription |
| v0.3.0 | `generate_manager_report`, `generate_security_report`, `generate_sector_report`, `check_report_status`, `wait_and_download_report` | Standard 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."

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. |

## 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/developers/>.

## 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>.
