Metadata-Version: 2.5
Name: fmpsdk-mcp
Version: 20260829.1
Summary: Model Context Protocol server for the fmpsdk Financial Modeling Prep library.
Project-URL: Homepage, https://github.com/daxm/fmpsdk
Project-URL: Repository, https://github.com/daxm/fmpsdk
Project-URL: Issues, https://github.com/daxm/fmpsdk/issues
Author-email: Dax Mickelson <github@daxm.net>
License-Expression: BSD-3-Clause
License-File: LICENSE.md
Keywords: claude,finance,financial-modeling-prep,fmp,llm,mcp,model-context-protocol,stocks
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: fastmcp<4,>=2.9
Requires-Dist: fmpsdk>=20260824
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# fmpsdk-mcp

<!-- mcp-name: io.github.daxm/fmpsdk-mcp -->

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
the [`fmpsdk`](https://pypi.org/project/fmpsdk/) library — the full Financial
Modeling Prep API — to an MCP client such as Claude Desktop or Claude Code.

Published to PyPI as [`fmpsdk-mcp`](https://pypi.org/project/fmpsdk-mcp/); it
lives in the [fmpsdk repo](https://github.com/daxm/fmpsdk) under `mcp/`. It is a
separate package so `pip install fmpsdk` never pulls in `fastmcp`.

## What it exposes

| Layer | Tools |
|---|---|
| **Curated** (use first) | `get_quote`, `get_company_profile`, `get_income_statement`, `get_balance_sheet`, `get_cash_flow`, `get_key_metrics`, `get_financial_ratios`, `get_historical_prices`, `search_symbol`, `get_stock_news` |
| **Discovery** (the other ~228 endpoints, at runtime) | `list_fmp_endpoints`, `describe_fmp_endpoint`, `call_fmp_endpoint` |
| **Resource** | `fmpsdk://llms.txt` — orientation for the underlying package |

Every tool is a read-only `GET`. Large list results from `call_fmp_endpoint`
are paged (50 rows) with `page` / `total` / `more`; the `bulk` group and the
whole-asset-class `batch_*_quotes` endpoints are refused — use the `fmpsdk`
library directly for dataset-scale work.

## Install

Needs [`uv`](https://docs.astral.sh/uv/) (for `uvx`) and an
[FMP API key](https://site.financialmodelingprep.com/developer/docs).

**Claude Code:**

```sh
claude mcp add fmpsdk -s user -e FMP_API_KEY=your-fmp-api-key -- uvx fmpsdk-mcp
```

**Claude Desktop** — add to `claude_desktop_config.json`:

```jsonc
{
  "mcpServers": {
    "fmpsdk": {
      "command": "uvx",
      "args": ["fmpsdk-mcp"],
      "env": { "FMP_API_KEY": "your-fmp-api-key" }
    }
  }
}
```

`uvx` fetches and caches the package on first launch (a few seconds). Pin a
version with `uvx fmpsdk-mcp@20260829.0`.

To run an unreleased revision straight from a branch instead:

```sh
uvx --from git+https://github.com/daxm/fmpsdk@master#subdirectory=mcp fmpsdk-mcp
```

## Develop

```sh
cd mcp
uv sync
uv run fastmcp dev fmpsdk_mcp/server.py   # opens the MCP Inspector
FMP_API_KEY=... uv run fmpsdk-mcp         # run the stdio server directly
uv run --extra test pytest               # the test suite
```

Cut a release with `mcp/deploy_a_release.sh` after bumping `__version__` in
`fmpsdk_mcp/__init__.py` — it runs the gate, then tags `mcp-v<version>` and
pushes, which triggers `.github/workflows/publish-mcp.yml`.

## Related: `openapi.json`

The repo root ships an `openapi.json` describing this same API surface,
generated by `python tools/gen_openapi.py`. It is introspected from the
`fmpsdk` source — **FMP publishes no OpenAPI/Swagger document**, and this file
is not fetched from or endorsed by FMP.
