Borsdata MCP 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"].

Related MCP server: massive-mcp

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

Stock Prices

Financial Reports

KPI Screener (latest values)

KPI History

Holdings (Pro+ only)

Calendar

Reference Data

Other

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

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