stockportfolio-mcp
by avisre
README.md
# stockportfolio-mcp
**Filing-grounded US financial data and SEC filing research for your agent.** Figures retain their
fiscal periods and source links; missing values are not estimated. Coverage is US-listed companies
that report in USD.
```bash
# Create or manage an API key → https://www.stockportfolio.pro/api
```
## Install
The hosted MCP server supports OAuth 2.1/DCR. Clients that support remote Streamable HTTP can
connect directly to `https://www.stockportfolio.pro/mcp` and sign in. The local npm bridge is for
clients that need stdio and requires a StockPortfolio.pro API key.
## Install the Cursor plugin
The Cursor Marketplace plugin connects to the hosted MCP server. After the plugin is listed, install
it from Cursor's Customize page and complete the sign-in prompt. If your client does not offer a
remote-MCP sign-in for `https://www.stockportfolio.pro/mcp`, send your API key as a header instead.
To configure a remote server manually, add one of these entries to `~/.cursor/mcp.json` or the
project's `.cursor/mcp.json`:
```json
{
"mcpServers": {
"stockportfolio": {
"url": "https://www.stockportfolio.pro/mcp"
}
}
}
```
```json
{
"mcpServers": {
"stockportfolio": {
"url": "https://www.stockportfolio.pro/mcp",
"headers": { "Authorization": "Bearer your-api-key" }
}
}
}
```
Continuing use needs a StockPortfolio.pro account; the plugin itself is free and MIT.
## Install the local stdio bridge
Add this to your MCP client's config and restart it:
**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"stockportfolio": {
"command": "npx",
"args": ["-y", "stockportfolio-mcp"],
"env": { "STOCKPORTFOLIO_API_KEY": "your-key-here" }
}
}
}
```
The stdio bridge requires `STOCKPORTFOLIO_API_KEY` (or `MCP_API_KEY`) in its environment. It does
not provide anonymous keyless access. Create a key from the API page linked above.
Requires Node 18 or newer; `npx` fetches the package on first run. Nothing else to install —
this package bundles everything it needs.
## Tools
| tool | what it returns |
|------|-----------------|
| `search_companies` | Resolve a company name or ticker to a covered US-listed company. |
| `get_company_fundamentals` | Period-based financial statements with SEC filing sources. |
| `search_filings` | Search filing metadata by company, form, and date range. |
| `get_filing` | Read selected excerpts from an SEC filing. |
| `ask_filings` | Research a question against company filings and return supporting pulls. |
| `get_recent_filings` | Review recent filings across covered companies. |
| `screen_companies` | Screen the covered company universe. |
| `get_filing_changes` | Compare a company's recent filings of the same form. |
| `get_red_flags` | Surface warning signs computed from filed statements. |
| `sp_health` | Free liveness probe. |
Research tools consume the allowance attached to the signed-in account. Current plans, credit costs,
and trial availability are listed on the API page; they can change, so this README does not repeat
price or allowance figures.
Every successful financial or filing response includes the relevant company, fiscal period, and SEC
filing source URL. Filing excerpts retain their filing URL; supplemental data is identified by
source. Missing values are returned as missing rather than estimated. The live `/mcp` endpoint
advertises the current tool schemas to clients during connection, so the list above is the current
source of truth for available tools.
## What's in this package
A stdio MCP server that proxies to the hosted endpoint at
`https://www.stockportfolio.pro/mcp`. It reads JSON-RPC on stdin, forwards each request with your
key as a bearer header, and relays the reply to stdout. No filing data, no model code and no
server logic ship in the tarball — the only thing it holds is the key you give it, and it sends
that key nowhere except that endpoint.
Because the endpoint is stateless, one bridge per client is fine and there is no session to resume
— a dropped connection is rebuilt on the next call.
## Troubleshooting
| symptom | cause |
|---------|-------|
| `The API key was rejected` | `STOCKPORTFOLIO_API_KEY` is missing, revoked, or pasted with quotes. |
| `Out of credits for this month` | The account's allowance is spent. See current options on the API page. |
| `Rate limited` | Too many concurrent calls; retry shortly. |
| `npx` can't find the package | Node 18+ is required. `npx -y stockportfolio-mcp` from a terminal shows the same error your client sees. |
| Client shows no tools | Restart the client after editing the config — the MCP config is read at startup. |
The bridge prints its errors to stderr, which most MCP clients surface in their log pane. To see
them directly, run it yourself:
```bash
STOCKPORTFOLIO_API_KEY=your-key npx -y stockportfolio-mcp
```
## Links
- Pricing and key management: <https://stockportfolio.pro/api?utm_source=npm&utm_medium=integration&utm_campaign=stockportfolio-mcp>
- REST API (same data, HTTP): <https://stockportfolio.pro/api/v1>
- Source and coverage: <https://www.stockportfolio.pro/>
Informational research only — not investment advice. Fund data is Yahoo-derived and not
redistributable.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues