@allratestoday/mcp-server 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,111 @@
+# AllRatesToday MCP Server
+
+MCP server that gives AI coding tools — **Claude Code**, **Cursor**, **Claude Desktop**, and any other Model Context Protocol client — real-time currency exchange rates, historical data, and financial news from [AllRatesToday](https://allratestoday.com).
+
+Ask your assistant things like:
+
+- *"What's the current USD to EUR rate?"*
+- *"Show me the GBP/JPY rate over the last 30 days."*
+- *"Convert 250 USD into CAD using a real rate."*
+- *"List every supported currency."*
+
+## Install
+
+```bash
+npm install -g @allratestoday/mcp-server
+```
+
+Or run without installing via `npx @allratestoday/mcp-server`.
+
+## Quick setup
+
+### Claude Code
+
+```bash
+claude mcp add allratestoday -- npx -y @allratestoday/mcp-server
+```
+
+Then set your API key:
+
+```bash
+claude mcp env allratestoday ALLRATES_API_KEY=art_live_xxxxx
+```
+
+### Cursor
+
+Edit `~/.cursor/mcp.json` (or your project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "allratestoday": {
+      "command": "npx",
+      "args": ["-y", "@allratestoday/mcp-server"],
+      "env": {
+        "ALLRATES_API_KEY": "art_live_xxxxx"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "allratestoday": {
+      "command": "npx",
+      "args": ["-y", "@allratestoday/mcp-server"],
+      "env": {
+        "ALLRATES_API_KEY": "art_live_xxxxx"
+      }
+    }
+  }
+}
+```
+
+Restart the app after editing.
+
+## Get an API key
+
+1. Register at [allratestoday.com/register](https://allratestoday.com/register).
+2. Verify your email.
+3. Copy your key from the dashboard — it looks like `art_live_xxxxx`.
+
+The free plan includes 300 requests/month. Paid plans start at €4.99/mo.
+
+## Tools exposed
+
+| Tool | API key | Description |
+|---|---|---|
+| `get_exchange_rate` | no | Current mid-market rate between two currencies. |
+| `get_historical_rates` | no | Historical data points over `1d`, `7d`, `30d`, or `1y`. |
+| `get_rates_authenticated` | yes | Multi-target rates and higher limits. |
+| `list_currencies` | no | All supported currencies with codes, names, symbols. |
+| `get_financial_news` | no | Latest financial news from major sources. |
+
+Public endpoints work without a key — set `ALLRATES_API_KEY` only if you want higher limits or to use the authenticated endpoint.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `ALLRATES_API_KEY` | *(unset)* | Your AllRatesToday API key. Required for `get_rates_authenticated`. |
+| `ALLRATES_BASE_URL` | `https://allratestoday.com/api` | Override for self-hosted or staging environments. |
+
+## Development
+
+```bash
+git clone https://github.com/cahthuranag/mcp-server.git
+cd mcp-server
+npm install
+npm run build
+node dist/index.js    # server runs on stdio — hit Ctrl+C to exit
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,63 @@
+export interface ClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare class AllRatesTodayError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, body?: unknown | undefined);
+}
+export declare class AllRatesTodayClient {
+    private readonly apiKey?;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: ClientOptions);
+    private request;
+    getRate(source: string, target: string): Promise<{
+        rate: number;
+        source: string;
+    }>;
+    getHistoricalRates(source: string, target: string, period?: '1d' | '7d' | '30d' | '1y'): Promise<{
+        source: string;
+        target: string;
+        period: string;
+        source_api?: string;
+        data: {
+            date: string;
+            rate: number;
+            timestamp: number;
+        }[];
+    }>;
+    getAuthenticatedRates(params: {
+        source?: string;
+        target?: string;
+        time?: string;
+        group?: 'hour' | 'day' | 'week' | 'month';
+    }): Promise<{
+        rate: number;
+        source: string;
+        target: string;
+        time: string;
+    }[]>;
+    listSymbols(): Promise<{
+        currencies: {
+            code: string;
+            name: string;
+            symbol: string;
+        }[];
+        count: number;
+    }>;
+    getNews(): Promise<{
+        status: string;
+        totalResults: number;
+        articles: {
+            title: string;
+            description?: string;
+            url: string;
+            image?: string;
+            publishedAt?: string;
+            source?: string;
+        }[];
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,73 @@
+const DEFAULT_BASE_URL = 'https://allratestoday.com/api';
+const USER_AGENT = `allratestoday-mcp/0.1.0`;
+export class AllRatesTodayError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'AllRatesTodayError';
+    }
+}
+export class AllRatesTodayClient {
+    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, requireAuth = false) {
+        const url = new URL(this.baseUrl + path);
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== '')
+                url.searchParams.set(key, value);
+        }
+        const headers = {
+            'Accept': 'application/json',
+            'User-Agent': USER_AGENT,
+        };
+        if (requireAuth) {
+            if (!this.apiKey) {
+                throw new AllRatesTodayError('This endpoint requires an API key. Set ALLRATES_API_KEY or pass apiKey in the MCP config.');
+            }
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        else if (this.apiKey) {
+            headers['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 msg = (body && typeof body === 'object' && 'error' in body && typeof body.error === 'string'
+                ? body.error
+                : `HTTP ${res.status}`);
+            throw new AllRatesTodayError(msg, res.status, body);
+        }
+        return body;
+    }
+    getRate(source, target) {
+        return this.request('/rate', { source, target });
+    }
+    getHistoricalRates(source, target, period = '7d') {
+        return this.request('/historical-rates', { source, target, period });
+    }
+    getAuthenticatedRates(params) {
+        return this.request('/v1/rates', params, true);
+    }
+    listSymbols() {
+        return this.request('/v1/symbols', {});
+    }
+    getNews() {
+        return this.request('/news', {});
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { AllRatesTodayClient, AllRatesTodayError } from './client.js';
+const CCY = {
+    type: 'string',
+    description: 'ISO 4217 currency code (e.g. USD, EUR, GBP).',
+    minLength: 3,
+    maxLength: 3,
+};
+const tools = [
+    {
+        name: 'get_exchange_rate',
+        description: 'Get the current mid-market exchange rate between two currencies. Returns a single rate number. No API key required.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                source: CCY,
+                target: CCY,
+            },
+            required: ['source', 'target'],
+        },
+    },
+    {
+        name: 'get_historical_rates',
+        description: 'Get historical exchange-rate data points for a currency pair over a period. Periods: 1d (hourly), 7d (daily), 30d (daily), 1y (weekly). No API key required.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                source: CCY,
+                target: CCY,
+                period: {
+                    type: 'string',
+                    enum: ['1d', '7d', '30d', '1y'],
+                    default: '7d',
+                    description: 'Time period to fetch history for.',
+                },
+            },
+            required: ['source', 'target'],
+        },
+    },
+    {
+        name: 'get_rates_authenticated',
+        description: 'Get rates with higher limits and multi-target support. Requires an AllRatesToday API key (ALLRATES_API_KEY). Supports comma-separated targets like "EUR,GBP,JPY".',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                source: CCY,
+                target: {
+                    type: 'string',
+                    description: 'One or more target codes, comma-separated.',
+                },
+                time: {
+                    type: 'string',
+                    format: 'date-time',
+                    description: 'Optional historical ISO 8601 timestamp.',
+                },
+                group: {
+                    type: 'string',
+                    enum: ['hour', 'day', 'week', 'month'],
+                    description: 'Optional grouping window.',
+                },
+            },
+            required: ['source', 'target'],
+        },
+    },
+    {
+        name: 'list_currencies',
+        description: 'List all supported currencies with code, name, and symbol. No API key required. Cached 24h upstream.',
+        inputSchema: { type: 'object', additionalProperties: false, properties: {} },
+    },
+    {
+        name: 'get_financial_news',
+        description: 'Get the latest financial and currency-market news from Bloomberg, Investing.com, and Google News. No API key required.',
+        inputSchema: { type: 'object', additionalProperties: false, properties: {} },
+    },
+];
+function text(s) {
+    const out = typeof s === 'string' ? s : JSON.stringify(s, null, 2);
+    return { content: [{ type: 'text', text: out }] };
+}
+async function main() {
+    const client = new AllRatesTodayClient({
+        apiKey: process.env.ALLRATES_API_KEY,
+        baseUrl: process.env.ALLRATES_BASE_URL,
+    });
+    const server = new Server({ name: 'allratestoday-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args = {} } = req.params;
+        try {
+            switch (name) {
+                case 'get_exchange_rate': {
+                    const { source, target } = args;
+                    return text(await client.getRate(source, target));
+                }
+                case 'get_historical_rates': {
+                    const { source, target, period = '7d' } = args;
+                    return text(await client.getHistoricalRates(source, target, period));
+                }
+                case 'get_rates_authenticated': {
+                    return text(await client.getAuthenticatedRates(args));
+                }
+                case 'list_currencies': {
+                    return text(await client.listSymbols());
+                }
+                case 'get_financial_news': {
+                    return text(await client.getNews());
+                }
+                default:
+                    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+            }
+        }
+        catch (err) {
+            const message = err instanceof AllRatesTodayError
+                ? `AllRatesToday error${err.status ? ` (${err.status})` : ''}: ${err.message}`
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            return { content: [{ type: 'text', text: message }], isError: true };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Keep process alive; stdio transport handles shutdown.
+}
+main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error('Fatal:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@allratestoday/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for AllRatesToday — let AI coding tools (Claude Code, Cursor, Claude Desktop) fetch real-time and historical currency exchange rates.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "currency",
+    "exchange-rate",
+    "forex",
+    "allratestoday"
+  ],
+  "license": "MIT",
+  "homepage": "https://allratestoday.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cahthuranag/mcp-server.git"
+  },
+  "bugs": "https://github.com/cahthuranag/mcp-server/issues",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "allratestoday-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}