Metadata-Version: 2.4
Name: datavidence-financials
Version: 0.1.0
Summary: MCP server for the Datavidence Financials API: normalized US-GAAP financial statements from SEC EDGAR, as tools for LLM agents.
Author-email: Datavidence LLC <admin@datavidence.ai>
License: MIT
Project-URL: Homepage, https://financials.datavidence.ai
Project-URL: Documentation, https://github.com/vijaykas/financial-ledgers-api/blob/main/mcp_server/README.md
Project-URL: Repository, https://github.com/vijaykas/financial-ledgers-api
Keywords: mcp,model-context-protocol,sec,edgar,financial-statements,xbrl,fundamentals,finance,llm,agents,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp==2.1.1
Requires-Dist: httpx>=0.27
Dynamic: license-file

# MCP server (AI-native layer)

Exposes the Datavidence Financials API as MCP **tools** for LLM agents (Claude
Desktop, LangChain, custom frameworks). It's a **standalone** component that
forwards over HTTP to the REST API, so the core service keeps its pinned deps
(the MCP SDK needs a much newer pydantic/uvicorn — see `docs/13`).

## Install

Published on PyPI as **`datavidence-financials`**. Run it with no clone using
[uv](https://docs.astral.sh/uv/) — it installs into a throwaway environment:

```
FL_API_KEY=sandbox_demo_key uvx datavidence-financials
```

or install it as a persistent tool with pipx:

```
pipx install datavidence-financials
FL_API_KEY=sandbox_demo_key datavidence-financials
```

`sandbox_demo_key` returns sample data with no signup; set `FL_API_KEY` to your
real key for live data (see **Config** below). The server speaks MCP over stdio,
so an MCP client launches it — see the Claude Desktop setup below.

## Tools
- **`get_financials`** — normalized income statement + balance sheet + cash flow
  for a company/year; supports `as_of` (point-in-time), `include_provenance`
  (per-value SEC source URLs), `include_ratios`.
- **`get_financials_batch`** — the same, for up to 25 companies in one call
  (comma-separated tickers/ciks); per-symbol results, counts as one quota unit.
- **`list_filings`** — recent SEC filings for a company (discover available years).
- **`get_usage`** — the key's monthly quota state (tier, used, remaining, reset);
  free to call, consumes no quota.

Errors surface the API's `recovery_action`, so agents self-correct.

## Run it
```
python -m venv .venv && . .venv/bin/activate
pip install -r mcp_server/requirements.txt
FL_API_KEY=sandbox_demo_key python -m mcp_server.server   # stdio transport
```
`sandbox_demo_key` returns sample data with no signup — good for a first run.
Swap in your real RapidAPI/AWS key for live data.

Config (env): `FL_API_KEY` (required), `FL_API_BASE_URL` (default the production
origin), `FL_API_KEY_HEADER` (default `X-API-Key`), `FL_API_TIMEOUT` (default 30).

## Claude Desktop

**Recommended (published package):** point Claude Desktop at the `uvx` launcher —
no clone, no venv, no `PYTHONPATH`:

```json
{
  "mcpServers": {
    "datavidence-financials": {
      "command": "uvx",
      "args": ["datavidence-financials"],
      "env": { "FL_API_KEY": "sandbox_demo_key" }
    }
  }
}
```

Fully quit (Cmd+Q) and reopen Claude Desktop; the tools appear. Swap in your real
key for live data.

**Quick setup (macOS):** one command creates the venv, installs deps, verifies the
tools, and registers the server with Claude Desktop (backs up + merges your
existing config):
```
mcp_server/setup_claude_desktop.sh            # uses the sandbox key
mcp_server/setup_claude_desktop.sh <your-key> # or your real key
```
Then fully quit (Cmd+Q) and reopen Claude Desktop.

**Manual:** Add to `claude_desktop_config.json` (point `command` at the venv's python, and
set the repo dir so `mcp_server` is importable):
```json
{
  "mcpServers": {
    "datavidence-financials": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/absolute/path/to/financial-api",
      "env": { "FL_API_KEY": "sandbox_demo_key" }
    }
  }
}
```
Restart Claude Desktop; the two tools appear. Ask e.g. "get AAPL's FY2023
financials with ratios" to exercise `get_financials`.

## Deployment note (docs/13 §2.1)
For a marketplace channel, set `FL_API_BASE_URL` to the **gateway** endpoint and
`FL_API_KEY`/`FL_API_KEY_HEADER` to the gateway's key/header, so calls are metered
by RapidAPI / AWS Data Exchange (BYOK) rather than hitting the locked origin
directly. That's the M3 deployment step.
