@allratestoday/central-bank-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AllRatesToday
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# Central Bank Rates MCP Server — @allratestoday/central-bank-mcp
+
+[![npm version](https://img.shields.io/npm/v/@allratestoday/central-bank-mcp.svg)](https://www.npmjs.com/package/@allratestoday/central-bank-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@allratestoday/central-bank-mcp.svg)](https://www.npmjs.com/package/@allratestoday/central-bank-mcp)
+[![license](https://img.shields.io/npm/l/@allratestoday/central-bank-mcp.svg)](./LICENSE)
+[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-1.x-blue.svg)](https://modelcontextprotocol.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6.svg)](https://www.typescriptlang.org/)
+
+**Give your AI assistant the official exchange rates that compliance, tax, and accounting actually require. A Model Context Protocol server that lets Claude Code, Cursor, Claude Desktop, Windsurf, and any MCP-compatible client fetch published central-bank and tax-authority rates from 60+ institutions — ECB, Fed, Bank of Japan, HMRC, US Treasury, and more — via the [AllRatesToday API](https://allratestoday.com/central-bank-rates-api/).**
+
+After installation, your assistant can answer questions like:
+
+- *"What is the ECB's official USD/EUR rate today?"*
+- *"What HMRC rate should I use for this March invoice?"*
+- *"Show me the Bank of Japan's official rate for every day of Q1."*
+- *"Compare the official USD/LKR rate across every central bank that publishes one."*
+
+## ⚖️ Official rates vs mid-market rates
+
+Everything this server returns is an **official published rate**: fixed once the institution publishes it, carrying that institution's own publication date — the number tax authorities, auditors, and customs require. It is *not* the live market rate. For **live mid-market rates** (price display, conversion, anything that should track the market), use the companion server [`@allratestoday/mcp-server`](https://www.npmjs.com/package/@allratestoday/mcp-server). The two can diverge by several percent — pick by use case. Methodology: [allratestoday.com/official-rates-methodology](https://allratestoday.com/official-rates-methodology/).
+
+## 🚀 Why this server?
+
+- 🏛️ **60+ official sources** — central banks (ECB, Fed, BOJ, SNB, RBI, …) plus tax authorities (HMRC, US Treasury, …), each served from its own published tables
+- 📅 **Point-in-time correctness** — ask for any date; weekends and holidays roll back to the rate legally in force, and the response tells you which publication date applied
+- 📊 **Cross-bank comparison** — one call returns every institution's rate for a pair, with min/max/median and spread stats
+- 🧮 **Honest derivations** — pairs a bank doesn't publish directly are cross-computed only within that bank's own table and flagged `derived`; banks are never mixed
+- 🧰 **Five focused tools** — small surface, easy for the model to use correctly
+- 🔌 **Works everywhere MCP does** — stdio transport, MCP 1.x; Claude Code, Cursor, Claude Desktop, Windsurf, or any generic host
+
+## 🔑 Get your API key
+
+The server **will not start** without a valid `ALLRATES_API_KEY`. A free key covers the latest published tables — **no credit card required**. Dated tables and history need a paid plan.
+
+1. Register at [allratestoday.com/register](https://allratestoday.com/register) — 30 seconds
+2. Verify your email
+3. Copy your key from the dashboard (format: `art_live_xxxxx`)
+4. Use it as `ALLRATES_API_KEY` in the configs below
+
+## 📦 Installation
+
+```bash
+# Run without installing (recommended)
+npx -y @allratestoday/central-bank-mcp
+```
+
+```bash
+# Or install globally
+npm install -g @allratestoday/central-bank-mcp
+central-bank-mcp
+```
+
+Both commands launch the stdio MCP server and wait for a client to connect — your MCP client launches them as a subprocess.
+
+## 🏁 Quick setup per client
+
+### Claude Code
+
+```bash
+claude mcp add central-bank-rates -- npx -y @allratestoday/central-bank-mcp
+claude mcp env central-bank-rates ALLRATES_API_KEY=art_live_xxxxx
+```
+
+Restart Claude Code. Verify by asking: *"Which central banks can you fetch official rates from?"*
+
+### Cursor
+
+Edit `~/.cursor/mcp.json` (or `.cursor/mcp.json` inside your project):
+
+```json
+{
+  "mcpServers": {
+    "central-bank-rates": {
+      "command": "npx",
+      "args": ["-y", "@allratestoday/central-bank-mcp"],
+      "env": {
+        "ALLRATES_API_KEY": "art_live_xxxxx"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config) and add the same `mcpServers` block as the Cursor example above, then restart Claude Desktop.
+
+## 🧰 Tools
+
+| Tool | What it does | Plan |
+|---|---|---|
+| `list_central_banks` | All covered institutions with codes, metadata, latest date | Free |
+| `get_official_rates` | A bank's published table (or one pair), latest or for a given date | Free (latest) / Paid (dated) |
+| `get_official_rate_history` | Date-by-date official series for one pair | Paid, billed ~1 call per month covered |
+| `compare_official_rates` | One pair across every bank, with spread stats | Free |
+| `get_publication_calendar` | Dates a bank actually published (no values) | Free |
+
+## 🔒 Privacy
+
+Only the request parameters and your API key ever reach allratestoday.com — never conversation context.
+
+## 📚 More from AllRatesToday
+
+- [Central bank REST API docs](https://allratestoday.com/central-bank-rates-api/)
+- [Per-bank npm SDKs](https://github.com/AllRates-Today)
+- [`@allratestoday/mcp-server`](https://www.npmjs.com/package/@allratestoday/mcp-server) — live mid-market rates MCP server
+
+## License
+
+MIT © AllRatesToday

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+export interface ClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare class CentralBankApiError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: unknown;
+    constructor(message: string, status?: number | undefined, body?: unknown);
+}
+export interface CbRate {
+    base: string;
+    quote: string;
+    type: string;
+    value: number;
+}
+export declare class CentralBankClient {
+    private readonly apiKey?;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: ClientOptions);
+    private request;
+    listBanks(): Promise<{
+        banks: Array<Record<string, unknown>>;
+        disclaimer: string;
+    }>;
+    getRates(bank: string, opts?: {
+        date?: string;
+        source?: string;
+        target?: string;
+    }): Promise<Record<string, unknown>>;
+    getHistory(bank: string, opts: {
+        symbol?: string;
+        source?: string;
+        target?: string;
+        from?: string;
+        to?: string;
+    }): Promise<Record<string, unknown>>;
+    compareBanks(source: string, target: string): Promise<Record<string, unknown>>;
+    getAvailability(bank: string, opts: {
+        year?: string;
+        from?: string;
+        to?: string;
+    }): Promise<Record<string, unknown>>;
+}

package/dist/client.js

@@ -0,0 +1,90 @@
+import { VERSION } from './version.js';
+const DEFAULT_BASE_URL = 'https://allratestoday.com/api';
+export class CentralBankApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'CentralBankApiError';
+    }
+}
+function errorMessage(status, upstream) {
+    switch (status) {
+        case 400:
+            return upstream ?? 'Bad request — check the bank code, currency codes, or date format';
+        case 401:
+            return 'Invalid AllRatesToday API key';
+        case 402:
+        case 403:
+            return upstream ?? 'This endpoint requires a paid AllRatesToday plan';
+        case 404:
+            return upstream ?? 'Unknown bank code or unsupported currency pair for this bank';
+        case 429:
+            return 'AllRatesToday API quota exceeded';
+        default:
+            return upstream ? `HTTP ${status} — ${upstream}` : `HTTP ${status}`;
+    }
+}
+export class CentralBankClient {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    constructor(options = {}) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async request(path, query = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== '')
+                url.searchParams.set(key, value);
+        }
+        if (!this.apiKey) {
+            throw new CentralBankApiError('AllRatesToday API key is required. Sign up free at https://allratestoday.com/register to get a key, then set ALLRATES_API_KEY in your MCP config.');
+        }
+        const headers = {
+            'Accept': 'application/json',
+            'User-Agent': `central-bank-mcp/${VERSION}`,
+            'Authorization': `Bearer ${this.apiKey}`,
+        };
+        const res = await this.fetchImpl(url.toString(), { method: 'GET', headers });
+        const text = await res.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            body = text;
+        }
+        if (!res.ok) {
+            const upstream = body && typeof body === 'object' && 'error' in body && typeof body.error === 'string'
+                ? body.error
+                : undefined;
+            throw new CentralBankApiError(errorMessage(res.status, upstream), res.status, body);
+        }
+        return body;
+    }
+    listBanks() {
+        return this.request('/v1/central-banks');
+    }
+    // date undefined -> /latest; date given -> /{YYYY-MM-DD} (paid plans).
+    getRates(bank, opts = {}) {
+        const path = `/v1/central-bank/${encodeURIComponent(bank)}/${opts.date ?? 'latest'}`;
+        return this.request(path, {
+            source: opts.source,
+            target: opts.target,
+        });
+    }
+    getHistory(bank, opts) {
+        return this.request(`/v1/central-bank/${encodeURIComponent(bank)}/history`, opts);
+    }
+    compareBanks(source, target) {
+        return this.request('/v1/central-banks/rates', { source, target });
+    }
+    getAvailability(bank, opts) {
+        return this.request(`/v1/central-bank/${encodeURIComponent(bank)}/availability`, opts);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { CentralBankClient, CentralBankApiError } from './client.js';
+import { VERSION } from './version.js';
+const BANK_DESC = "Bank/authority code as returned by list_central_banks (lowercase, e.g. 'ecb', 'fed', 'boj', 'hmrc', 'cbsl'). Call list_central_banks first if unsure — codes are short abbreviations of the institution, not country codes.";
+const bank = z
+    .string()
+    .regex(/^[a-z0-9-]{2,20}$/i, 'must be a bank code like ecb, fed, boj — see list_central_banks')
+    .describe(BANK_DESC);
+const ccy = z
+    .string()
+    .regex(/^[A-Za-z]{3}$/, 'must be a 3-letter ISO 4217 currency code')
+    .describe("ISO 4217 currency code, 3 letters, case-insensitive (e.g. 'USD', 'EUR', 'LKR').");
+const isoDate = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, 'must be YYYY-MM-DD')
+    .describe('Calendar date in YYYY-MM-DD format.');
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+function ok(structured) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+        structuredContent: structured,
+    };
+}
+function fail(err) {
+    const message = err instanceof CentralBankApiError
+        ? `AllRatesToday error${err.status ? ` (${err.status})` : ''}: ${err.message}`
+        : err instanceof Error
+            ? err.message
+            : String(err);
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+async function main() {
+    const apiKey = process.env.ALLRATES_API_KEY;
+    if (!apiKey) {
+        console.error([
+            '',
+            '  AllRatesToday central-bank MCP server requires an API key.',
+            '',
+            '  1. Sign up free at https://allratestoday.com/register (free tier — no card required)',
+            '  2. Copy your API key from the dashboard',
+            '  3. Set ALLRATES_API_KEY in your MCP client config:',
+            '',
+            '     "central-bank-rates": {',
+            '       "command": "npx",',
+            '       "args": ["-y", "@allratestoday/central-bank-mcp"],',
+            '       "env": { "ALLRATES_API_KEY": "art_live_..." }',
+            '     }',
+            '',
+        ].join('\n'));
+        process.exit(1);
+    }
+    const client = new CentralBankClient({
+        apiKey,
+        baseUrl: process.env.ALLRATES_BASE_URL,
+    });
+    const server = new McpServer({ name: 'central-bank-mcp', version: VERSION });
+    server.registerTool('list_central_banks', {
+        title: 'List covered central banks & tax authorities',
+        description: "Call this FIRST when you need a bank code, or when the user asks 'which central banks do you cover?' or 'do you have rates from X?'. Returns { banks: [{ code, name, country, home_ccy, rate_types, latest date, ... }], disclaimer } for 60+ institutions — central banks (ECB, Fed, BOJ, ...) plus tax authorities (HMRC, US Treasury, ...). The `code` field is what every other tool takes as its `bank` parameter. Cheap to call.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        try {
+            return ok(await client.listBanks());
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('get_official_rates', {
+        title: "Get a bank's official published rates",
+        description: "Use this for OFFICIAL rates a specific institution published — 'what is the ECB rate for USD?', 'Bank of Japan official rate on 2026-03-14', 'HMRC rate for invoicing'. These are the fixed rates in force for compliance, tax, customs, and accounting — NOT live market rates. Omit `date` for the newest published table; give `date` (paid plans) for the table in force on that day (weekends/holidays roll back to the last published date — the response's rate_date says which). Omit source/target for the bank's full table { rates: [{ base, quote, type, value }] }; give both for one pair — cross-computed via the bank's own home currency when not directly published, flagged `derived`. For live mid-market rates use the @allratestoday/mcp-server package instead.",
+        inputSchema: {
+            bank,
+            date: isoDate
+                .optional()
+                .describe('Optional YYYY-MM-DD. Omit for the latest published table (all plans). A specific date requires a paid plan.'),
+            source: ccy.optional().describe('Optional. With target, narrows to one pair.'),
+            target: ccy.optional().describe('Optional. With source, narrows to one pair.'),
+        },
+        annotations: READ_ONLY,
+    }, async ({ bank: bankCode, date, source, target }) => {
+        try {
+            if ((source && !target) || (!source && target)) {
+                return fail(new Error('Provide both source and target, or neither.'));
+            }
+            return ok(await client.getRates(bankCode.toLowerCase(), {
+                date,
+                source: source?.toUpperCase(),
+                target: target?.toUpperCase(),
+            }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('get_official_rate_history', {
+        title: "Get a bank's official rate history",
+        description: "Use this for a date-by-date series of one bank's OFFICIAL rates — 'ECB USD rate for every day of 2025', 'how did the CBSL official rate move last quarter'. Returns one row per published date: { series: [{ date, rate, rate_type, derived, method }] }. Give either `symbol` (matches either side of the pair vs the bank's home currency) or a source+target pair. Defaults to the last year when from/to omitted. Paid plans only, and BILLED BY VOLUME: one API call per month of history covered (a year-long series costs ~12 calls) — keep ranges as narrow as the question needs. For publication dates without values (free) use get_publication_calendar.",
+        inputSchema: {
+            bank,
+            symbol: ccy
+                .optional()
+                .describe("One currency vs the bank's home currency, e.g. 'USD'. Alternative to source+target."),
+            source: ccy.optional(),
+            target: ccy.optional(),
+            from: isoDate.optional().describe('Start date. Defaults to one year ago.'),
+            to: isoDate.optional().describe('End date. Defaults to today.'),
+        },
+        annotations: READ_ONLY,
+    }, async ({ bank: bankCode, symbol, source, target, from, to }) => {
+        try {
+            if (!symbol && !(source && target)) {
+                return fail(new Error('Provide either symbol, or both source and target.'));
+            }
+            return ok(await client.getHistory(bankCode.toLowerCase(), {
+                symbol: symbol?.toUpperCase(),
+                source: source?.toUpperCase(),
+                target: target?.toUpperCase(),
+                from,
+                to,
+            }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('compare_official_rates', {
+        title: 'Compare one pair across every bank',
+        description: "Use this when the user wants one currency pair across ALL institutions at once — 'what does each central bank say USD/EUR is?', 'spread between official USD/LKR rates', 'which bank has the highest official rate for X?'. One call returns every covered bank's latest official rate for the pair plus spread stats { min, max, median, spread_bps } over fresh sources (stale quarterly publishers are returned but excluded from stats). Rates a bank doesn't publish directly are cross-computed within that bank's own table only — banks are never mixed. Methodology: https://allratestoday.com/official-rates-methodology/",
+        inputSchema: { source: ccy, target: ccy },
+        annotations: READ_ONLY,
+    }, async ({ source, target }) => {
+        try {
+            return ok(await client.compareBanks(source.toUpperCase(), target.toUpperCase()));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('get_publication_calendar', {
+        title: "Get a bank's publication calendar",
+        description: "Use this to see WHICH dates a bank actually published a rate table — 'did the ECB publish on 2026-01-01?', 'how often does the US Treasury publish?'. Returns dates only, no rate values, so it is available on every plan (unlike history). Gaps reveal weekends, holidays, and weekly/quarterly publication cadence. Give ?year=YYYY or a from/to range; large ranges are capped and flagged `truncated`.",
+        inputSchema: {
+            bank,
+            year: z
+                .string()
+                .regex(/^\d{4}$/, 'must be YYYY')
+                .optional()
+                .describe("Whole calendar year, e.g. '2026'. Alternative to from/to."),
+            from: isoDate.optional(),
+            to: isoDate.optional(),
+        },
+        annotations: READ_ONLY,
+    }, async ({ bank: bankCode, year, from, to }) => {
+        try {
+            return ok(await client.getAvailability(bankCode.toLowerCase(), { year, from, to }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,3 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+export const VERSION = require('../package.json').version;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@allratestoday/central-bank-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.cahthuranag/central-bank-mcp",
+  "description": "MCP server for official central-bank and tax-authority exchange rates — let AI tools (Claude Code, Cursor, Claude Desktop) fetch published rates from 60+ institutions (ECB, Fed, HMRC, BOJ, ...) via the AllRatesToday API.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "central-bank",
+    "official-rates",
+    "exchange-rate",
+    "ecb",
+    "tax",
+    "allratestoday"
+  ],
+  "license": "MIT",
+  "homepage": "https://allratestoday.com/central-bank-rates-api/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AllRates-Today/central-bank-mcp.git"
+  },
+  "bugs": "https://github.com/AllRates-Today/central-bank-mcp/issues",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "central-bank-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2"
+  }
+}