@allratestoday/central-bank-mcp 0.3.2 → 0.3.4

package/README.md

@@ -7,6 +7,7 @@ Website: https://allratestoday.com/central-bank-rates-api/ · Hosted endpoint (n
 [![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/)
+[![Central Bank Mcp on AI Agents Listing](https://aiagentslisting.com/central-bank-mcp/badge.svg?claim=837813c0572a45328913a7361270b559)](https://aiagentslisting.com/mcp/central-bank-mcp)
 
 **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 121 central banks and 3 tax authorities — ECB, Fed, Bank of Japan, HMRC, US Treasury, and more — via the [AllRatesToday API](https://allratestoday.com/central-bank-rates-api/).**
 
@@ -26,9 +27,9 @@ Everything this server returns is an **official published rate**: fixed once the
 - 🏛️ **121 central banks + 3 tax authorities** — 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
+- 🧮 **Honest derivations** — with an API key, pairs a bank doesn't publish directly are cross-computed only within that bank's own table and flagged `derived`; banks are never mixed. Keyless serves only published pairs and their inverses
 - 🔓 **Works with no API key** — installs and answers out of the box; the latest published table of every source is open
-- 🧰 **Five focused tools** — small surface, easy for the model to use correctly
+- 🧰 **Six 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
 
 ## 🔓 Keyless mode — what works with no setup
@@ -37,11 +38,11 @@ Install it with no configuration at all and it starts, connects, and answers:
 
 | Tool | Keyless | What you get |
 |---|---|---|
-| `list_central_banks` | ✅ | Every covered institution, from a catalogue bundled with the package (no coverage dates). |
-| `get_official_rates` | ✅ | The **latest published table** of any source, or one pair from it, with the publisher's own `rate_date`. |
-| `get_official_rates` with a `date` | 🔑 | One sentence explaining how to get a key. |
-| `get_official_rate_history` | 🔑 | Same. |
-| `compare_official_rates` | 🔑 | Same. |
+| `list_central_banks` | ✅ | Every covered institution (121 central banks, 3 tax authorities and the composite), from a catalogue bundled with the package (no coverage dates). |
+| `get_official_rates` | ✅ | The **latest published table** of any source, or one published pair (or its inverse) from it, with the publisher's own `rate_date`. Cross pairs need a key. |
+| `get_official_rates` with a `date` | 🔑 | One sentence explaining that dated tables need a paid plan. |
+| `get_official_rate_history` | 🔑 | Same (paid plan). |
+| `compare_official_rates` | 🔑 | One sentence explaining how to get a free key. |
 | `get_publication_calendar` | 🔑 | Same. |
 | `request_trial_key` | ✅ | Self-issues a 100-call, 7-day key with no account and adopts it for the session. |
 
@@ -51,9 +52,9 @@ endpoint — free to use with a visible attribution link back to allratestoday.c
 
 ## 🔑 Get your API key (free)
 
-A key adds historical dates, time series, cross-bank comparison and publication
-calendars. The free tier covers the latest published tables and light historical
-use — **no credit card required**. Deep history and dated tables need a paid plan.
+A free key adds cross-bank comparison, cross-computed pairs and publication
+calendars — 300 lifetime calls, **no credit card required**. Dated (historical)
+tables and time series need a paid plan: free and trial keys get a 403 for them.
 
 1. Register at [allratestoday.com/register](https://allratestoday.com/register) — 30 seconds
 2. Verify your email
@@ -80,7 +81,7 @@ Everything below still applies for other MCP clients.
 
 ## ☁️ Hosted endpoint — nothing to install
 
-The same tools also run as a hosted **Streamable HTTP** MCP server (together with the tools of the sibling AllRatesToday server, nine in total). Paste the URL into any client that supports remote MCP — Claude.ai and Claude Desktop connectors, ChatGPT, Cursor, VS Code, Codex, Gemini CLI:
+The same six tools also run as a hosted **Streamable HTTP** MCP server, together with the five tools of the sibling AllRatesToday server — eleven in total on the hosted endpoint (this npm package itself exposes six). Paste the URL into any client that supports remote MCP — Claude.ai and Claude Desktop connectors, ChatGPT, Cursor, VS Code, Codex, Gemini CLI:
 
 ```
 https://allratestoday.com/api/mcp

package/dist/banks.js

@@ -106,6 +106,25 @@ export const BANK_CATALOG = [
     { "code": "boz", "name": "Bank of Zambia", "country": "Zambia", "home_ccy": "ZMW", "kind": "central_bank", "npm": "boz-exchange-rate" },
     { "code": "rbm", "name": "Reserve Bank of Malawi", "country": "Malawi", "home_ccy": "MWK", "kind": "central_bank", "npm": "rbm-exchange-rate" },
     { "code": "nbkr", "name": "National Bank of the Kyrgyz Republic", "country": "Kyrgyzstan", "home_ccy": "KGS", "kind": "central_bank", "npm": "nbkr-exchange-rate" },
+    { "code": "lb", "name": "Bank of Lithuania", "country": "Lithuania", "home_ccy": "EUR", "kind": "central_bank", "npm": "bank-of-lithuania-exchange-rate" },
+    { "code": "bcc", "name": "Banque Centrale du Congo", "country": "DR Congo", "home_ccy": "CDF", "kind": "central_bank", "npm": "banque-centrale-du-congo-exchange-rate" },
+    { "code": "cbbd", "name": "Central Bank of Barbados", "country": "Barbados", "home_ccy": "BBD", "kind": "central_bank", "npm": "central-bank-of-barbados-exchange-rate" },
+    { "code": "cbl", "name": "Central Bank of Libya", "country": "Libya", "home_ccy": "LYD", "kind": "central_bank", "npm": "central-bank-of-libya-exchange-rate" },
+    { "code": "cbg", "name": "Central Bank of The Gambia", "country": "Gambia", "home_ccy": "GMD", "kind": "central_bank", "npm": "central-bank-of-the-gambia-exchange-rate" },
+    { "code": "brh", "name": "Banque de la République d'Haïti", "country": "Haiti", "home_ccy": "HTG", "kind": "central_bank", "npm": "brh-exchange-rate" },
+    { "code": "rma", "name": "Royal Monetary Authority of Bhutan", "country": "Bhutan", "home_ccy": "BTN", "kind": "central_bank", "npm": "rma-bhutan-exchange-rate" },
+    { "code": "nbt", "name": "National Bank of Tajikistan", "country": "Tajikistan", "home_ccy": "TJS", "kind": "central_bank", "npm": "national-bank-of-tajikistan-exchange-rate" },
+    { "code": "cbbz", "name": "Central Bank of Belize", "country": "Belize", "home_ccy": "BZD", "kind": "central_bank", "npm": "central-bank-of-belize-exchange-rate" },
+    { "code": "rbf", "name": "Reserve Bank of Fiji", "country": "Fiji", "home_ccy": "FJD", "kind": "central_bank", "npm": "reserve-bank-of-fiji-exchange-rate" },
+    { "code": "mma", "name": "Maldives Monetary Authority", "country": "Maldives", "home_ccy": "MVR", "kind": "central_bank", "npm": "maldives-monetary-authority-exchange-rate" },
+    { "code": "bcm", "name": "Banque Centrale de Mauritanie", "country": "Mauritania", "home_ccy": "MRU", "kind": "central_bank", "npm": "banque-centrale-de-mauritanie-exchange-rate" },
+    { "code": "rbz", "name": "Reserve Bank of Zimbabwe", "country": "Zimbabwe", "home_ccy": "ZWG", "kind": "central_bank", "npm": "reserve-bank-of-zimbabwe-exchange-rate" },
+    { "code": "bon", "name": "Bank of Namibia", "country": "Namibia", "home_ccy": "NAD", "kind": "central_bank", "npm": "bank-of-namibia-exchange-rate" },
+    { "code": "bfm", "name": "Central Bank of Madagascar (BFM)", "country": "Madagascar", "home_ccy": "MGA", "kind": "central_bank", "npm": "central-bank-of-madagascar-exchange-rate" },
+    { "code": "cbt", "name": "Central Bank of Turkmenistan", "country": "Turkmenistan", "home_ccy": "TMT", "kind": "central_bank", "npm": "central-bank-of-turkmenistan-exchange-rate" },
+    { "code": "bccu", "name": "Banco Central de Cuba", "country": "Cuba", "home_ccy": "CUP", "kind": "central_bank", "npm": "banco-central-de-cuba-exchange-rate" },
+    { "code": "bsl", "name": "Bank of Sierra Leone", "country": "Sierra Leone", "home_ccy": "SLE", "kind": "central_bank", "npm": "bank-of-sierra-leone-exchange-rate" },
+    { "code": "bcstp", "name": "Banco Central de São Tomé e Príncipe", "country": "São Tomé and Príncipe", "home_ccy": "STN", "kind": "central_bank", "npm": "bcstp-exchange-rate" },
     { "code": "hmrc", "name": "HM Revenue & Customs", "country": "United Kingdom", "home_ccy": "GBP", "kind": "tax", "npm": "hmrc-exchange-rate" },
     { "code": "bazg", "name": "Swiss Federal Office for Customs and Border Security", "country": "Switzerland", "home_ccy": "CHF", "kind": "tax", "npm": "bazg-exchange-rate" },
     { "code": "ustreasury", "name": "U.S. Department of the Treasury", "country": "United States", "home_ccy": "USD", "kind": "tax", "npm": "ustreasury-exchange-rate" },

package/dist/client.d.ts

@@ -14,7 +14,7 @@ export declare class CentralBankApiError extends Error {
  * instead of a bare 401.
  */
 export declare class NeedsKeyError extends CentralBankApiError {
-    constructor(what: string);
+    constructor(what: string, paid?: boolean);
 }
 export interface CbRate {
     base: string;

package/dist/client.js

@@ -17,9 +17,13 @@ export class CentralBankApiError extends Error {
  * instead of a bare 401.
  */
 export class NeedsKeyError extends CentralBankApiError {
-    constructor(what) {
-        super(`This lookup (${what}) needs an AllRatesToday API key. The free tier covers it — ` +
-            'sign up at https://allratestoday.com/register (no card, under a minute), then set ' +
+    constructor(what, paid = false) {
+        super(`This lookup (${what}) needs an AllRatesToday API key. ` +
+            (paid
+                ? 'Dated tables and history series need a PAID plan (free and trial keys get a 403) — ' +
+                    'see https://allratestoday.com/pricing, then set '
+                : 'The free tier covers it (300 lifetime calls) — sign up at ' +
+                    'https://allratestoday.com/register (no card, under a minute), then set ') +
             'ALLRATES_API_KEY in the MCP server config and restart. Without a key this server can ' +
             'still return the latest published table for any source (get_official_rates) and the ' +
             'source catalogue (list_central_banks).');
@@ -105,7 +109,7 @@ export class CentralBankClient {
                 url.searchParams.set(key, value);
         }
         if (!this.apiKey)
-            throw new NeedsKeyError(path);
+            throw new NeedsKeyError(path, /\/history$|\/\d{4}-\d{2}-\d{2}$/.test(path));
         const headers = {
             'Accept': 'application/json',
             'User-Agent': `central-bank-mcp/${VERSION}`,
@@ -180,7 +184,7 @@ export class CentralBankClient {
         // cost). A past date is not — that is the metered part.
         if (this.keyless) {
             if (opts.date)
-                return Promise.reject(new NeedsKeyError(`${bank} table for ${opts.date}`));
+                return Promise.reject(new NeedsKeyError(`${bank} table for ${opts.date}`, true));
             return this.openRequest(`/open/central-bank/${encodeURIComponent(bank)}`, { source: opts.source, target: opts.target });
         }
         const path = `/v1/central-bank/${encodeURIComponent(bank)}/${opts.date ?? 'latest'}`;

package/dist/index.js

@@ -49,11 +49,12 @@ async function main() {
             '    • get_official_rates       — the latest published table (any source)',
             '    • request_trial_key        — self-issue a 100-call, 7-day key without an account',
             '',
-            '  Needs a free API key (historical dates, time series, cross-bank compare,',
-            '  publication calendars):',
-            '    1. https://allratestoday.com/register — free tier, no card, under a minute',
+            '  Needs a free API key (cross-bank compare, publication calendars):',
+            '    1. https://allratestoday.com/register — free tier (300 lifetime calls), no card',
             '    2. Add to this server\'s MCP config:  "env": { "ALLRATES_API_KEY": "art_live_..." }',
             '',
+            '  Needs a paid plan (dated tables, history series): https://allratestoday.com/pricing',
+            '',
         ].join('\n'));
     }
     const client = new CentralBankClient({
@@ -63,7 +64,7 @@ async function main() {
     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.",
+        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 121 central banks + 3 tax authorities (plus a composite) — 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 () => {
@@ -76,7 +77,7 @@ async function main() {
     });
     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.",
+        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 — with an API key, pairs not directly published are cross-computed via the bank's own home currency and flagged `derived`; keyless serves only published pairs and their inverses. For live mid-market rates use the @allratestoday/mcp-server package instead.",
         inputSchema: {
             bank,
             date: isoDate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allratestoday/central-bank-mcp",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "mcpName": "com.allratestoday/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 120+ institutions (ECB, Fed, HMRC, BOJ, ...) via the AllRatesToday API.",
   "keywords": [
@@ -15,7 +15,15 @@
     "tax",
     "allratestoday",
     "exchangerate",
-    "exchange rate"
+    "exchange rate",
+    "currency-api",
+    "currency-exchange-rates",
+    "forex-api",
+    "currency-conversion",
+    "currency-exchange",
+    "currency-rates",
+    "currency",
+    "forex"
   ],
   "license": "MIT",
   "homepage": "https://allratestoday.com/central-bank-rates-api/",