boi-mcp

Official Bank of Israel exchange rates (שערים יציגים) and interest rate for any MCP client.

A Model Context Protocol server that gives AI agents the official representative exchange rates published daily by the Bank of Israel, the rate on any past date (with automatic previous-business-day fallback), history and statistics over a range, ILS conversions and cross rates, and the Bank of Israel policy interest rate with its change history.

It talks directly to the Bank of Israel's free, public SDMX REST API at edge.boi.gov.il: no API key, no scraping, no third-party FX feed.

Part of a small family of Israeli MCP servers: hebrew-il-mcp (local validators: ID, phone, VAT, IBAN, plates, holidays) and il-opendata-mcp (data.gov.il datasets).

Tools

Every tool returns both human-readable JSON text and structuredContent. Bad input (unknown currency, malformed or future date, empty range) produces an MCP isError result with a clear message instead of crashing the session.

Currency inputs are forgiving: usd, $, €, £, ¥, דולר, יורו all work.

Details that are easy to get wrong

• Quoting units. The BOI quotes JPY per 100 yen and LBP per 10 pounds (UNIT_MULT in SDMX). rate is kept exactly as published and ils_per_unit is normalized, so conversions are always right.

• "Today" is Israeli time. Dates default to Asia/Jerusalem, not UTC, so a request at 01:00 in Tel Aviv asks for the right day.

• No data ≠ error. The API answers HTML 404 when a query matches nothing (e.g. a Saturday). The client maps that to "no observations" and the tools fall back or explain.

Related MCP server: eco-policy-mcp

Quick start

Claude Desktop / Cursor / any MCP client

{
  "mcpServers": {
    "boi": {
      "command": "npx",
      "args": ["-y", "github:Shtibel1/boi-mcp"]
    }
  }
}

Claude Desktop: put this in claude_desktop_config.json. Cursor: ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

Or from a local clone:

npm install && npm run build
node dist/cli.js   # speaks MCP over stdio

Then ask your agent things like:

• "What is the dollar's representative rate today, and how did it move this month?"

• "Convert 2,500 EUR to shekels at the rate of 2026-10-04."

• "מה ריבית בנק ישראל ומתי היא השתנתה לאחרונה?"

Hosted: Streamable HTTP

npx -y github:Shtibel1/boi-mcp --http --port 3000
# → boi-mcp listening on http://127.0.0.1:3000/mcp
curl http://127.0.0.1:3000/healthz   # {"status":"ok","name":"boi-mcp","version":"0.1.0"}

{ "mcpServers": { "boi": { "url": "http://127.0.0.1:3000/mcp" } } }

The HTTP mode is stateless: every POST /mcp gets a fresh server and transport, there are no session ids, and GET/DELETE /mcp return 405, so instances can sit behind any load balancer. Bodies over 1 MB get 413, malformed JSON gets 400.

Docker

The image runs the HTTP mode as the unprivileged node user on 0.0.0.0:3000 with a HEALTHCHECK against /healthz:

docker build -t boi-mcp .
docker run --rm -p 3000:3000 -e ALLOWED_ORIGINS=https://app.example boi-mcp

CI builds the image on every push and smoke-tests it: health check, a real tools/list call, the origin guard and the non-root user.

As a library

import { BoiClient } from "boi-mcp";

const boi = new BoiClient();
const { rates } = await boi.getLatestRates(["USD", "EUR"]);
const onSunday = await boi.getRate("USD", "2026-10-04"); // → Friday 2026-10-02, is_fallback: true
const history = await boi.getRateHistory("EUR", "2026-10-01", "2026-11-14");
const { result } = await boi.convert({ amount: 100, from: "EUR", to: "JPY" });
const policy = await boi.getInterestRate();

Live example

Real output from the built server against the live Bank of Israel API, run on 2026-11-15 (Sunday, Asia/Jerusalem — the latest rates are Friday's):

{
  "currency": "USD",
  "name": "US Dollar",
  "name_he": "דולר ארה\"ב",
  "rate": 3.199,
  "unit": 1,
  "ils_per_unit": 3.199,
  "date": "2026-11-13",
  "requested_date": "2026-11-14",
  "is_fallback": true,
  "days_back": 1,
  "source": "Bank of Israel SDMX API (edge.boi.gov.il)"
}

Architecture

flowchart LR
  C["MCP client<br/>(Claude Desktop, Cursor, agents)"] -- stdio --> CLI[cli.ts]
  R["Remote agents"] -- "POST /mcp" --> H["http.ts<br/>stateless Streamable HTTP<br/>origin check · /healthz"]
  CLI --> S["server.ts<br/>zod schemas · isError results"]
  CLI -- "--http" --> H
  H -- "new server per request" --> S
  S --> BOI
  subgraph L["src/lib — no MCP imports"]
    BOI["boi.ts<br/>injectable fetch · SDMX client<br/>fallback · stats · conversion"]
    CSV["csv.ts<br/>RFC 4180 parser"]
    CUR["currencies.ts<br/>14 currencies · units · aliases"]
    DT["dates.ts<br/>Asia/Jerusalem today"]
    BOI --> CSV
    BOI --> CUR
    BOI --> DT
  end
  BOI -- "HTTPS · format=csv" --> API["edge.boi.gov.il<br/>SDMX v2: EXR · BR"]
  APP["Your TS app"] -- import --> L

How the data is fetched

All with format=csv. The fallback is done by the API itself (endperiod + lastNObservations=1), so a holiday week never needs a retry loop.

Layout

src/
  lib/boi.ts         injectable-fetch SDMX client: rates, fallback, history stats, conversion, policy rate
  lib/csv.ts         small RFC 4180 CSV parser (quoted Hebrew comments, doubled quotes, CRLF, BOM)
  lib/currencies.ts  supported currencies, quoting units, Hebrew names and aliases
  lib/dates.ts       Asia/Jerusalem "today", strict YYYY-MM-DD validation
  server.ts          MCP tool wiring (zod schemas)
  http.ts            stateless Streamable HTTP transport (node:http, no framework)
  cli.ts             entry: stdio by default, --http for hosted mode
test/
  fixtures/          real BOI API responses captured on 2026-11-15 (see fixtures/README.md)
  *.test.ts          55 vitest tests; fetch is mocked with the fixtures, so CI never hits the network

Development

npm test          # vitest, replaying recorded BOI responses (no network)
npm run typecheck
npm run build

Attribution

This is an unofficial client. Exchange rates and interest rates come from the Bank of Israel and are subject to its terms of use. Representative rates are reference rates, not dealing quotes. This project has no affiliation with the Bank of Israel.

Roadmap

• Publish to npm so npx boi-mcp works without the GitHub shorthand

• Effective exchange-rate indices (nominal/real basket) and USD/ILS implied volatility from the same EXR dataflow

• CPI and inflation expectations series

• Small in-memory cache for the HTTP mode (rates change once per business day)

• Render / Fly one-click deploy

Contributing

Issues and PRs are welcome. Keep API logic in src/lib with unit tests and add an end-to-end case in test/server.test.ts for new tools. New fixtures must be real captured responses — never hand-written API data.

License

MIT © Nadav Shtibel