belex-mcp

MCP server for Belgrade Stock Exchange (Belex) and National Bank of Serbia (NBS) data. The first open-source Model Context Protocol server targeting the Serbian financial market.

What is this?

belex-mcp is a Node.js / TypeScript MCP server that exposes Belex quotes, indices, and NBS exchange rates / key macro indicators as standardized tools that LLM clients (Claude Desktop, Cursor, custom agents) can call. Until now, asking an LLM about Serbian markets meant shipping custom scraping inside the agent or pretending the data didn't exist. This collapses that into one npx belex-mcp.

Quick start (Claude Desktop)

1. Make sure you have Node.js 20 or newer.
2. Open your Claude Desktop config file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Add belex-mcp to the mcpServers section:

{
  "mcpServers": {
    "belex": {
      "command": "npx",
      "args": ["-y", "belex-mcp"]
    }
  }
}

4. Restart Claude Desktop. Ask: "What was the EUR/RSD midrate yesterday?". See examples/demo-prompts.md for more.

Tools

All tools return JSON. Timestamps are ISO 8601 in Europe/Belgrade. Prices are RSD unless noted.

| Tool | Purpose | |---|---| | belex_list_companies | Instruments listed on Belex | | belex_get_company_profile | Profile for a single symbol | | belex_get_quote | Latest quote (last, OHLCV, change %) | | belex_get_historical_prices | Daily OHLCV bars across a range | | belex_get_index | BELEX15 / BELEXLINE current value | | belex_get_index_constituents | Index members and weights | | belex_get_market_summary | EOD turnover, gainers, losers, most-traded | | nbs_list_currencies | Currencies NBS publishes | | nbs_get_exchange_rate | Mid / buy / sell for a date | | nbs_get_exchange_rate_series | Daily mid-rates across a range | | nbs_get_reference_rate | NBS key policy rate | | nbs_get_inflation | YoY and MoM CPI |

Full tool reference: docs/tools.md.

Examples

Three demo conversations that exercise multiple tools live in examples/demo-prompts.md.

Data sources & disclaimer

Data is sourced from public pages of belex.rs and nbs.rs and cached in process (LRU; no external dependencies). belex-mcp is not affiliated with the Belgrade Stock Exchange or the National Bank of Serbia. Prices and rates are intended for informational use; for trading or settlement, use the authoritative source directly.

The HTTP layer enforces a politeness budget of one request per second per host, exponential backoff with jitter, and a stable User-Agent.

Architecture

LLM client (Claude Desktop / Cursor)
        │  MCP JSON-RPC over stdio
        ▼
belex-mcp server
  ├── MCP SDK runtime
  ├── Tool registry + Zod input schemas
  ├── belexClient   ──► belex.rs (HTML)
  └── nbsClient     ──► nbs.rs (XML + HTML)
        ▼
HTTP layer (undici, retry+backoff, LRU cache, rate limiter)

Decisions and trade-offs are recorded as ADRs under docs/adr/.

Development

git clone https://github.com/filipovicfilip222-alt/belex-mcp.git
cd belex-mcp
npm install
npm run typecheck   # strict TS check
npm run lint        # ESLint flat config
npm test            # vitest unit tests
npm run test:integration   # opt-in; hits live sources

Repository layout follows §7 of the project docs. Every tool has a Zod input schema, a fixture-backed unit test, and a wrapper in src/clients/. See fixtures/README.md for fixture conventions.

Contributing

Conventional Commits (feat:, fix:, chore:, docs:, test:) only. One logical change per commit. Open an issue before any change touching more than three files.

License

MIT. See LICENSE.