Borsdata Server

MCP (Model Context Protocol) server that exposes the Borsdata financial data API as tools and resources for Claude. Covers Nordic and Global stocks, financial reports, KPIs, stock prices, holdings, and calendars.

Quick Start

Prerequisites

• Node.js 18+
• A Borsdata API key (requires Pro membership — apply via Borsdata MyPage)

Add to Claude Code

Run this from your project directory:

claude mcp add borsdata -- npx borsdata-mcp-server

Then set the API key as an environment variable. You can either:

1. Add to your shell profile (.bashrc, .zshrc, etc.):

   export BORSDATA_API_KEY=your-api-key-here
   

2. Or configure it in .mcp.json (project-level) manually:

   {
     "mcpServers": {
       "borsdata": {
         "command": "npx",
         "args": ["borsdata-mcp-server"],
         "env": {
           "BORSDATA_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

Add to Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "borsdata": {
      "command": "npx",
      "args": ["borsdata-mcp-server"],
      "env": {
        "BORSDATA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Alternative: Install globally

npm install -g borsdata-mcp-server

Then use "command": "borsdata-mcp-server" instead of npx borsdata-mcp-server in your config.

Alternative: Install from source

git clone https://github.com/carlwestman/borsdata-mcp-server.git
cd borsdata-mcp-server
npm install
npm run build

Then point your config at the built output (use the full path to where you cloned it):

{
  "mcpServers": {
    "borsdata": {
      "command": "node",
      "args": ["<path-to-cloned-repo>/dist/index.js"],
      "env": {
        "BORSDATA_API_KEY": "your-api-key-here"
      }
    }
  }
}

For example, if you cloned to ~/projects/borsdata-mcp-server, the args would be ["~/projects/borsdata-mcp-server/dist/index.js"].

---

Using with Claude — CLAUDE.md Snippet

For best results, add the Borsdata context to your project's CLAUDE.md so Claude knows how to use the tools effectively. Copy the contents of CLAUDE_MD_SNIPPET.md into your project's CLAUDE.md:

cat node_modules/borsdata-mcp-server/CLAUDE_MD_SNIPPET.md >> CLAUDE.md

Or copy it from the GitHub repo directly. This gives Claude the workflow, tool reference, parameter guide, and common KPI IDs it needs to use the server efficiently.

---

Tools (22 total)

Instruments

Tool	Description
search_instruments	Search Nordic instruments by name or ticker. Start here — you need the insId for most other tools.
list_instruments	List all Nordic instruments. Optional filters: instrument type, market, sector, country.
list_global_instruments	List all Global instruments. Requires Pro+.
get_instrument_descriptions	Get Swedish/English company descriptions for up to 50 instruments.

Stock Prices

Tool	Description
get_stock_prices	Historical end-of-day prices for one instrument. Up to 20 years. Supports date range and max count.
get_stock_prices_batch	Historical prices for up to 50 instruments in one call.
get_latest_prices	Latest price for all Nordic instruments.
get_prices_by_date	All Nordic prices for a specific date.

Financial Reports

Tool	Description
get_reports	Income statement, balance sheet, and cash flow for one instrument. Choose report type: year, r12, or quarter.
get_all_reports	All report types (year + r12 + quarter) for one instrument.
get_reports_batch	All report types for up to 50 instruments.

KPI Screener (latest values)

Tool	Description
get_kpi	One KPI value for one instrument (e.g., P/E ratio for Ericsson).
get_kpi_all	One KPI value for ALL Nordic instruments (useful for screening).
get_kpi_updated	When KPIs were last recalculated.

KPI History

Tool	Description
get_kpi_history	Historical KPI values for one instrument over time.
get_kpi_history_batch	Historical KPI values for up to 50 instruments.
get_kpi_summary	Summary of all available KPIs for one instrument.

Holdings (Pro+ only)

Tool	Description
get_insider_holdings	Insider trading activity (past 10 years) for up to 50 instruments.
get_short_positions	Short selling positions for all Nordic instruments.
get_buybacks	Share buyback data for up to 50 instruments.

Calendar

Tool	Description
get_report_calendar	Upcoming report release dates for up to 50 instruments.
get_dividend_calendar	Dividend dates and amounts for up to 50 instruments.

Reference Data

Tool	Description
list_branches	All industry branches (sub-categories of sectors).
list_countries	All Nordic countries.
list_markets	All stock exchanges/markets.
list_sectors	All sectors.

Other

Tool	Description
get_stock_splits	Stock splits for Nordic instruments within the last year.

---

MCP Resources (Knowledge Base)

The server exposes 3 MCP resources that agents can read to understand the API's opaque IDs and parameters. These are the key to making the tools usable — without them, an agent wouldn't know that "P/E ratio" maps to kpiId=2.

1. borsdata://guide/api-overview — API Guide

A comprehensive reference document that agents read first. Contains:

• Typical workflow: search for instrument by name → get insId → use insId with other tools
• Data tiers: what's available in Nordic Pro vs Global Pro+
• Rate limits: 100 calls/10 seconds, 10,000/day recommended max
• Instrument types: full ID-to-name mapping (0=Stocks, 1=Preference Stocks, 2=Nordic Index, etc.)
• Report types: year vs r12 (rolling 12 months) vs quarter, max counts, currency flag
• KPI parameters:
  • calcGroup: 1year, 3year, 5year, 7year, 10year, 15year, last
  • calc: high, low, mean, cagr, latest
  • reportType: year, r12, quarter
  • priceType: low, mean, high
• Common KPI IDs: P/E=2, P/S=3, P/B=4, Dividend Yield=1, EPS=6, ROE=34, ROA=35
• Report periods: 1=Q1, 2=Q2, 3=Q3, 4=Q4, 5=Full Year

2. borsdata://reference/kpi-metadata — KPI Lookup Table

Dynamic resource — fetched from the Borsdata API on first access, then cached. Returns a markdown table of ALL available KPI IDs:

| kpiId | English Name | Swedish Name | Format | IsString |
|-------|-------------|-------------|--------|----------|
| 1     | Dividend Yield | Direktavkastning | percentage | false |
| 2     | P/E          | P/E          | number | false    |
| 3     | P/S          | P/S          | number | false    |
| 4     | P/B          | P/B          | number | false    |
| 5     | Revenue Per Share | Omsättning/aktie | number | false |
| 6     | Earnings Per Share | Vinst/aktie | number | false |
| ...   | ...          | ...          | ...    | ...      |

This is the single most important resource. It lets agents translate human-readable KPI names (like "Return on Equity") into the numeric kpiId needed by get_kpi, get_kpi_all, and get_kpi_history.

3. borsdata://reference/report-fields — Report Field Metadata

Dynamic resource — fetched from the Borsdata API on first access, then cached. Returns a markdown table explaining what each field in a financial report means:

| Field Name              | English Name              | Swedish Name           | Format  |
|------------------------|--------------------------|----------------------|---------|
| revenues               | Revenues                 | Omsättning           | number  |
| gross_Income           | Gross Income             | Bruttoresultat       | number  |
| operating_Income       | Operating Income         | Rörelseresultat      | number  |
| profit_Before_Tax      | Profit Before Tax        | Resultat före skatt  | number  |
| earnings_Per_Share     | Earnings Per Share       | Vinst per aktie      | number  |
| total_Assets           | Total Assets             | Totala tillgångar    | number  |
| free_Cash_Flow         | Free Cash Flow           | Fritt kassaflöde     | number  |
| ...                    | ...                      | ...                  | ...     |

Agents use this to understand the 40+ fields returned by get_reports, get_all_reports, and get_reports_batch.

---

API Reference

This server wraps the Borsdata API v1. Additional documentation:

• Swagger UI
• API Wiki
• OpenAPI JSON

Rate Limits

• 100 calls per 10 seconds (enforced by the server's built-in rate limiter)
• Recommended daily maximum: 10,000 calls
• Data updates daily after ~20:00 UTC (end-of-day only, no intraday)

Data Tiers

Feature	Nordic Pro	Global Pro+
Nordic instruments	Yes	Yes
Global instruments	No	Yes
Stock prices (20yr)	Yes	Yes
Financial reports	Yes	Yes
KPIs	Yes	Yes
Calendars	Yes	Yes
Insider holdings	No	Yes
Short positions	No	Yes
Buybacks	No	Yes

---

Development (from source)

git clone https://github.com/carlwestman/borsdata-mcp-server.git
cd borsdata-mcp-server
npm install
npm run dev           # Run with tsx (auto-compiles TypeScript)
npm run build         # Compile to dist/
npm start             # Run compiled output
npm test              # Run tests (vitest)
npm run lint          # Lint with eslint

Project Structure

src/
  index.ts              # Entry point — McpServer + StdioServerTransport
  api/
    client.ts           # BorsdataClient HTTP wrapper
    rate-limiter.ts     # Sliding window rate limiter
    types.ts            # TypeScript interfaces for API responses
  tools/                # Tool registration (one file per domain)
  resources/            # MCP Resources (knowledge base)
  utils/
    errors.ts           # Structured error handling

License

ISC