# financial-datasets/mcp-server architecture

> Architecture diagram of the GitHub repository financial-datasets/mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/financial-datasets/mcp-server
- Repository: https://github.com/financial-datasets/mcp-server

## Overview

##### Project type + purpose (what you’re diagramming)
This repo is a **Python-based MCP (Model Context Protocol) server** that exposes a set of **tools** (RPC-like functions) to an MCP client (e.g., **Claude Desktop**). Those tools act as a thin integration layer over the **Financial Datasets** external API to fetch equities/crypto financial statements, prices, and news.

So the “system” is not a multi-service platform; it’s a **single service adapter** sitting between:
- **MCP Client (Claude Desktop / other assistants)**
and
- **Financial Datasets API (external SaaS)**

##### File tree analysis (how code is likely structured)
Top-level files only:

- `server.py` — the entire server implementation likely lives here:
- MCP server initialization (register tools)
- tool handlers (get_income_statements, etc.)
- outbound HTTP calls (via `httpx`)
- reading env vars (API key)
- `.env.example` — documents required env var(s), notably `FINANCIAL_DATASETS_API_KEY`
- `pyproject.toml` — Python packaging + deps
- `uv.lock` — pinned dependency lock
- `.python-version` — runtime version hint
- `.gitignore`, `LICENSE`, `README.md` — meta

Architecturally this indicates:
- **single-process** server
- minimal internal layering (might still have logical layers inside `server.py`, but not separate modules)
- no database, no queue, no cache visible in repo

##### README-derived architecture signals
Key runtime/interaction facts from README:
- Runs via `uv run server.py`
- Connects to Claude Desktop by configuring `claude_desktop_config.json` to execute this server as an MCP server process.
- Tools correspond to Financial Datasets endpoints (income statements, balance sheets, cash flows, stock prices, news, crypto).

This implies the main runtime topology:

##### 4a) Main components (separate into as many components as possible)

**Client side**
- **Claude Desktop (MCP Client)**
- “Tool invocation / MCP request”
- “Receives tool results / MCP response”
- config: `claude_desktop_config.json` (important: it defines command + args)

**This repo (your service)**
- **Financial Datasets MCP Server (Python process)**
- **MCP Runtime / Server Framework** (`mcp[cli]`)
- **Tool Registry**
- Income Statement Tool
- Balance Sheet Tool
- Cash Flow Tool
- Stock Price Tools (current, historical)
- Company News Tool
- Crypto Tools (list tickers, historical/current prices)
- **HTTP Client Layer** (`httpx`)
- **Config/Secrets**
- `.env` / environment variables
- `FINANCIAL_DATASETS_API_KEY`

**External**
- **Financial Datasets API** (HTTPS)
- endpoints for financial statements, prices, news, crypto

(Optionally) **Network/Internet** boundary between your server and Financial Datasets.

- Claude Desktop → MCP Server: “MCP tool call: get_income_statements(ticker, period, …)”
- MCP Server → Financial Datasets API: “HTTPS request via httpx (Authorization/API key)”
- Financial Datasets API → MCP Server: “JSON response”
- MCP Server → Claude Desktop: “MCP tool result (structured payload)”

Also show:
- Claude Desktop config → MCP Server process: “launches `uv run server.py`”
- Environment/.env → MCP Server: “reads FINANCIAL_DATASETS_API_KEY”

##### 4c) Architectural patterns/principles to highlight
- **Adapter / Facade pattern**: MCP tools provide a stable interface over an external API.
- **Stateless service**: no persistence implied; each request is independent.
- **Secrets via environment variables**: API key not in code.
- **Thin integration layer**: most logic is orchestration + validation + mapping external responses to tool outputs.

##### 4d) Relevant technologies to label explicitly
- Python 3.10+
- `mcp[cli]` (MCP server framework/runtime)
- `httpx` (outbound HTTP client)
- `uv` (packaging/runtime execution)
- Financial Datasets API (external SaaS)
- Claude Desktop (MCP client)

##### Labels (be explicit)
Use precise names taken from repo/README:
- “Financial Datasets MCP Server (`server.py`)”
- “MCP Tools: get_income_statements, get_balance_sheets, …”
- “Env: `FINANCIAL_DATASETS_API_KEY`”
- “Outbound: `httpx` → Financial Datasets API”

- protocol (MCP, HTTPS)
- payload type (tool args, JSON)
- auth mechanism (API key header/query, if known; otherwise “API key”)

##### Extra detail to capture (small repo, but still separate components)
To “separate into as many components as possible” without inventing things:
1) **Financial Statements** (income/balance/cash-flow)
2) **Market Data** (current/historical stock prices)
3) **Content + Crypto** (company news, crypto tickers/prices)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% External Client (MCP)
    %% =========================
    subgraph "Client Side"
        Claude["Claude Desktop (MCP Client)"]:::client
        ClaudeCfg["claude_desktop_config.json (launch config)"]:::doc
        ClaudeCfg -->|"defines_command+args"| Claude
    end

    %% =========================
    %% Local Machine Boundary
    %% =========================
    subgraph "Local Machine"
        direction TB

        subgraph "Financial Datasets MCP Server (Single Python Process)"
            direction TB

            UV["uv (runtime execution)"]:::runtime
            PyVer["Python version hint"]:::doc

            Server["Financial Datasets MCP Server (server.py)"]:::service

            subgraph "MCP Layer"
                direction TB
                MCP["MCP Runtime / Server Framework (mcp[cli])"]:::framework
                Registry["Tool Registry"]:::component
            end

            subgraph "Tool Handlers (MCP Tools)"
                direction TB

                subgraph "Financial Statements Tools"
                    direction TB
                    TIncome["get_income_statements"]:::tool
                    TBalance["get_balance_sheets"]:::tool
                    TCash["get_cash_flow_statements"]:::tool
                end

                subgraph "Market Data Tools"
                    direction TB
                    TPriceNow["get_stock_price_current"]:::tool
                    TPriceHist["get_stock_prices_historical"]:::tool
                end

                subgraph "Content + Crypto Tools"
                    direction TB
                    TNews["get_company_news"]:::tool
                    TCryptoTickers["get_crypto_tickers"]:::tool
                    TCryptoNow["get_crypto_price_current"]:::tool
                    TCryptoHist["get_crypto_prices_historical"]:::tool
                end
            end

            Shape["Response shaping / schema mapping"]:::component
            HTTPX["HTTP Client Layer (httpx)"]:::http

            Env["Environment variables (.env)"]:::doc
            ApiKey["FINANCIAL_DATASETS_API_KEY"]:::secret

            PyProject["Project Dependencies / Packaging (pyproject.toml)"]:::doc
            Lock["uv.lock (locked dependencies)"]:::doc
        end
    end

    %% =========================
    %% External SaaS
    %% =========================
    subgraph "Internet / External"
        FDAPI["Financial Datasets API (External SaaS)"]:::external
        subgraph "API Endpoints (conceptual)"
            direction TB
            EStmt["Statements (income/balance/cash-flow)"]:::externalSub
            EPrices["Prices (current/historical)"]:::externalSub
            ENews["News"]:::externalSub
            ECrypto["Crypto (tickers/prices)"]:::externalSub
        end
    end

    %% =========================
    %% Interactions / Data Flow
    %% =========================
    Claude -->|"launches_subprocess: uv run server.py"| UV
    UV -->|"executes"| Server
    PyVer -.->|"runtime_target"| UV

    Claude -->|"MCP_request: tool_call(args)"| MCP
    MCP -->|"dispatch_tool_call"| Registry

    Registry -->|"routes"| TIncome
    Registry -->|"routes"| TBalance
    Registry -->|"routes"| TCash
    Registry -->|"routes"| TPriceNow
    Registry -->|"routes"| TPriceHist
    Registry -->|"routes"| TNews
    Registry -->|"routes"| TCryptoTickers
    Registry -->|"routes"| TCryptoNow
    Registry -->|"routes"| TCryptoHist

    TIncome -->|"calls"| HTTPX
    TBalance -->|"calls"| HTTPX
    TCash -->|"calls"| HTTPX
    TPriceNow -->|"calls"| HTTPX
    TPriceHist -->|"calls"| HTTPX
    TNews -->|"calls"| HTTPX
    TCryptoTickers -->|"calls"| HTTPX
    TCryptoNow -->|"calls"| HTTPX
    TCryptoHist -->|"calls"| HTTPX

    Env -->|"provides"| ApiKey
    ApiKey -.->|"used_for_auth"| HTTPX

    HTTPX -->|"HTTPS_request (API_key) + JSON"| FDAPI
    FDAPI -->|"HTTPS_response JSON"| HTTPX

    HTTPX -->|"raw_JSON"| Shape
    Shape -->|"tool_result_payload"| MCP
    MCP -->|"MCP_response: tool_result"| Claude

    FDAPI -->|"serves"| EStmt
    FDAPI -->|"serves"| EPrices
    FDAPI -->|"serves"| ENews
    FDAPI -->|"serves"| ECrypto

    PyProject -.->|"declares_deps: mcp[cli], httpx"| Server
    Lock -.->|"pins_versions"| UV

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click Server "https://github.com/financial-datasets/mcp-server/blob/main/server.py"
    click Registry "https://github.com/financial-datasets/mcp-server/blob/main/server.py"
    click HTTPX "https://github.com/financial-datasets/mcp-server/blob/main/server.py"
    click MCP "https://github.com/financial-datasets/mcp-server/blob/main/pyproject.toml"
    click PyProject "https://github.com/financial-datasets/mcp-server/blob/main/pyproject.toml"
    click Env "https://github.com/financial-datasets/mcp-server/blob/main/.env.example"
    click Lock "https://github.com/financial-datasets/mcp-server/blob/main/uv.lock"
    click PyVer "https://github.com/financial-datasets/mcp-server/blob/main/.python-version"
    click Claude "https://github.com/financial-datasets/mcp-server/blob/main/README.md"
    click ClaudeCfg "https://github.com/financial-datasets/mcp-server/blob/main/README.md"

    %% =========================
    %% Styles
    %% =========================
    classDef client fill:#1f77b4,stroke:#0b3d91,stroke-width:2px,color:#ffffff
    classDef service fill:#2c7fb8,stroke:#084081,stroke-width:2px,color:#ffffff
    classDef framework fill:#3b8bc2,stroke:#08519c,stroke-width:2px,color:#ffffff
    classDef tool fill:#4ea3d8,stroke:#136aa8,stroke-width:1.5px,color:#ffffff
    classDef http fill:#2b8cbe,stroke:#08589e,stroke-width:2px,color:#ffffff
    classDef component fill:#7fcdbb,stroke:#1c7c7c,stroke-width:1.5px,color:#08306b
    classDef external fill:#f28e2b,stroke:#a65512,stroke-width:2px,color:#ffffff
    classDef externalSub fill:#f5b26b,stroke:#a65512,stroke-width:1.5px,color:#3b1f00
    classDef doc fill:#e5e7eb,stroke:#6b7280,stroke-width:1.5px,color:#111827
    classDef secret fill:#d1fae5,stroke:#059669,stroke-width:2px,color:#064e3b
    classDef runtime fill:#60a5fa,stroke:#1d4ed8,stroke-width:2px,color:#0b1020
```
