toolstem-mcp-server

# 📊 Toolstem — Financial Data MCP for AI Agents | Stock Analysis & DCF

[![npm version](https://img.shields.io/npm/v/toolstem-mcp-server)](https://www.npmjs.com/package/toolstem-mcp-server)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-active-teal)](https://registry.modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)

**Curated financial data MCP for AI agents — equity research in one call.**

Toolstem is the **financial data MCP** built for AI stock analysis, equity research, and agent-driven investment workflows. Real-time stock data, company fundamentals, DCF valuations, financial metrics, and the ability to compare companies side-by-side — all returned as flat, agent-friendly JSON with derived signals already computed.

Works natively with **Claude**, **OpenAI Agents SDK**, and **LangChain**. Pay-per-call pricing, no subscription. More finance MCP servers (SEC filings, insider transactions, institutional holdings) are on the way.

Unlike passthrough wrappers that just expose a vendor's REST API, every Toolstem tool **combines multiple data sources**, **derives signals**, and **pre-computes the math** an agent would otherwise have to do itself.

One call. One agent-friendly JSON response. No nested arrays to parse, no cross-endpoint stitching, no null-checking boilerplate.

---

## Quickstart — hosted endpoint (recommended)

Point your MCP client or agent at the hosted endpoint. **No API key, no infra, no setup.** Billing is per-call via [x402](https://www.x402.org) — the agent's wallet pays directly in USDC on Base mainnet.

```
https://mcp.toolstem.com/mcp/finance
```

- **No FMP API key required** — you do not bring or manage any upstream data key.
- **No infrastructure** — nothing to install, host, or keep running.
- **No setup** — connect an MCP client and call a tool.
- `initialize` and `tools/list` are **free** (discovery and schema introspection).
- Each `tools/call` costs **$0.01 USDC** on Base mainnet, settled via x402.

### Claude Desktop

Drop this into your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "toolstem-finance": {
      "url": "https://mcp.toolstem.com/mcp/finance"
    }
  }
}
```

Restart Claude Desktop, then ask: *"Use Toolstem to get a snapshot of NVDA."*

### Any MCP client (LangChain.js)

The official [`@langchain/mcp-adapters`](https://www.npmjs.com/package/@langchain/mcp-adapters) library connects directly to the hosted URL:

```ts
import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const client = new MultiServerMCPClient({
  toolstem_finance: {
    transport: "http",
    url: "https://mcp.toolstem.com/mcp/finance",
    // Add your x402-signing middleware via headers, OR run an x402
    // proxy locally and point url at it. See https://www.x402.org/clients.
  },
});

const tools = await client.getTools();
const agent = createReactAgent({ llm: new ChatOpenAI({ model: "gpt-4o-mini" }), tools });
await agent.invoke({ messages: "Compare AAPL, MSFT, and GOOGL on valuation and growth." });
```

Prefer to run the server yourself with your own FMP key? See [Advanced: self-host](#advanced-self-host) at the bottom.

Product page: <https://toolstem.com/finance/>.

---

## Pricing

- **MCP `initialize` and `tools/list` are free** — discovery, schema introspection, and health checks never cost anything.
- **`tools/call` costs $0.01 USDC on Base mainnet per invocation, paid via [x402](https://www.x402.org).** No API key, no signup, no marketplace account required — the agent's wallet pays directly.

---

## How it works

Toolstem ships as a Node MCP server (this repo) **and** as a hosted, x402-gated proxy.

```
Agent ──MCP──▶ Cloudflare Worker (x402 paywall) ──MCP──▶ Toolstem MCP server ──REST──▶ Financial Modeling Prep
                  │                                          │
                  └─ free: initialize, tools/list            └─ composite tool: fans out to 3–5 FMP endpoints
                  └─ paid: tools/call → 0.01 USDC on Base       in parallel, derives signals, returns flat JSON
```

- **Cloudflare Worker** terminates the public MCP connection at `mcp.toolstem.com` and enforces the x402 payment for `tools/call`.
- **MCP server** (this package) implements the 3 composite tools and talks to Financial Modeling Prep.
- **x402 on Base mainnet** handles the micropayment — settlement is sub-second, no off-chain accounts.

---

## Tools

Three composite tools, each one synthesizing multiple FMP endpoints with derived signals and pre-computed math.

| Tool | Title | Required input | Optional input |
|---|---|---|---|
| [`get_stock_snapshot`](#get_stock_snapshot) | Stock Snapshot | `symbol` (string) | — |
| [`get_company_metrics`](#get_company_metrics) | Company Metrics | `symbol` (string) | `period` (`annual` \| `quarter`, default `annual`) |
| [`compare_companies`](#compare_companies) | Company Comparison | `symbols` (string[2..5]) | — |

All three are read-only, idempotent, and safe for agent retry.

### `get_stock_snapshot`

Comprehensive stock overview combining quote, profile, DCF valuation, and rating into a single response.

**Input:**

```json
{
  "symbol": "AAPL"
}
```

**Example output (truncated):**

```json
{
  "symbol": "AAPL",
  "company_name": "Apple Inc.",
  "sector": "Technology",
  "industry": "Consumer Electronics",
  "exchange": "NASDAQ",
  "price": {
    "current": 178.52,
    "change": 2.34,
    "change_percent": 1.33,
    "day_high": 179.80,
    "day_low": 175.10,
    "year_high": 199.62,
    "year_low": 130.20,
    "distance_from_52w_high_percent": -10.57,
    "distance_from_52w_low_percent": 37.11
  },
  "valuation": {
    "market_cap": 2780000000000,
    "market_cap_readable": "$2.78T",
    "pe_ratio": 29.5,
    "dcf_value": 195.20,
    "dcf_upside_percent": 9.35,
    "dcf_signal": "FAIRLY VALUED"
  },
  "rating": {
    "score": 4,
    "recommendation": "Buy",
    "dcf_score": 5,
    "roe_score": 4,
    "roa_score": 4,
    "de_score": 5,
    "pe_score": 3
  },
  "fundamentals_summary": {
    "beta": 1.28,
    "avg_volume": 55000000,
    "employees": 164000,
    "ipo_date": "1980-12-12",
    "description": "Apple Inc. designs, manufactures..."
  },
  "meta": {
    "source": "Toolstem via Financial Modeling Prep",
    "timestamp": "2026-04-17T18:30:00Z",
    "data_delay": "End of day"
  }
}
```

**Derived fields (not in raw APIs):**

- `dcf_signal` — `UNDERVALUED` if DCF upside > 10%, `OVERVALUED` if < -10%, else `FAIRLY VALUED`.
- `market_cap_readable` — human-friendly `$2.78T`, `$450.2B`, `$12.5M` format.
- `distance_from_52w_high_percent` / `distance_from_52w_low_percent` — pre-computed range position.

---

### `get_company_metrics`

Deep fundamentals analysis — profitability, financial health, cash flow, growth, and per-share metrics — synthesized from 5 financial statements endpoints.

**Input:**

```json
{
  "symbol": "AAPL",
  "period": "annual"
}
```

`period` accepts `annual` (default) or `quarter`.

**Example output (truncated):**

```json
{
  "symbol": "AAPL",
  "period": "annual",
  "latest_period_date": "2025-09-30",
  "profitability": {
    "revenue": 394328000000,
    "revenue_readable": "$394.3B",
    "revenue_growth_yoy": 7.8,
    "net_income": 96995000000,
    "net_income_readable": "$97.0B",
    "gross_margin": 46.2,
    "operating_margin": 31.5,
    "net_margin": 24.6,
    "roe": 160.5,
    "roa": 28.3,
    "roic": 56.2,
    "margin_trend": "EXPANDING"
  },
  "financial_health": {
    "total_debt": 111000000000,
    "total_cash": 65000000000,
    "net_debt": 46000000000,
    "debt_to_equity": 1.87,
    "current_ratio": 1.07,
    "interest_coverage": 41.2,
    "health_signal": "STRONG"
  },
  "cash_flow": {
    "operating_cash_flow": 118000000000,
    "free_cash_flow": 104000000000,
    "free_cash_flow_readable": "$104.0B",
    "fcf_margin": 26.4,
    "capex": 14000000000,
    "dividends_paid": 15000000000,
    "buybacks": 89000000000,
    "fcf_yield": 3.7
  },
  "growth_3yr": {
    "revenue_cagr": 8.2,
    "net_income_cagr": 10.1,
    "fcf_cagr": 9.5,
    "growth_signal": "ACCELERATING"
  },
  "per_share": {
    "eps": 6.42,
    "book_value_per_share": 3.99,
    "fcf_per_share": 6.89,
    "dividend_per_share": 0.96,
    "payout_ratio": 14.9
  },
  "meta": {
    "source": "Toolstem via Financial Modeling Prep",
    "timestamp": "2026-04-17T18:30:00Z",
    "periods_analyzed": 3,
    "data_delay": "End of day"
  }
}
```

**Derived fields:**

- `margin_trend` — `EXPANDING`, `STABLE`, or `CONTRACTING` based on net margin series direction.
- `health_signal` — `STRONG`, `ADEQUATE`, or `WEAK` from debt-to-equity, current ratio, and interest coverage.
- `growth_signal` — `ACCELERATING`, `STEADY`, or `DECELERATING` based on YoY growth trajectory.
- `revenue_cagr`, `net_income_cagr`, `fcf_cagr` — compound annual growth rates over the analyzed window.
- `fcf_margin`, `fcf_yield` — pre-computed from cash flow + revenue + market cap.

---

### `compare_companies`

Side-by-side comparison of 2–5 companies across price, valuation, profitability, financial health, growth, dividends, and analyst ratings.

**Input:**

```json
{
  "symbols": ["AAPL", "MSFT", "GOOGL"]
}
```

`symbols` must be an array of 2 to 5 ticker strings.

**Example output (truncated):**

```json
{
  "symbols_compared": ["AAPL", "MSFT", "GOOGL"],
  "comparison_date": "2026-04-20T18:30:00Z",
  "companies": [
    {
      "symbol": "AAPL",
      "company_name": "Apple Inc.",
      "sector": "Technology",
      "price": { "current": 178.52, "change_percent": 1.33 },
      "valuation": { "pe_ratio": 29.5, "dcf_upside_percent": 9.35 },
      "profitability": { "net_margin": 24.6, "roe": 160.5, "roic": 56.2 },
      "financial_health": { "debt_to_equity": 1.87, "current_ratio": 1.07 },
      "growth": { "revenue_growth_yoy": 7.8, "earnings_growth_yoy": 10.1 },
      "dividend": { "d