@commoditypriceapi/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CommodityPriceAPI
+
+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,106 @@
+# CommodityPriceAPI MCP Server
+
+Official MCP server for [CommodityPriceAPI](https://commoditypriceapi.com). Exposes 8 MCP tools for real-time and historical commodity rates — gold, silver, oil, and 130+ other commodities — to any MCP-compatible client (Claude Desktop, Cursor, Windsurf, VS Code, Cline, etc).
+
+| Item      | Value                    |
+| --------- | ------------------------ |
+| Package   | `@commoditypriceapi/mcp` |
+| Transport | `stdio`                  |
+| Node.js   | `>=18`                   |
+
+## Quick Start
+
+1. [Get a free CommodityPriceAPI key](https://commoditypriceapi.com/auth/signup)
+2. Add this to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "commoditypriceapi": {
+      "command": "npx",
+      "args": ["-y", "@commoditypriceapi/mcp"],
+      "env": {
+        "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
+      }
+    }
+  }
+}
+```
+
+3. Restart your client.
+4. Test it: ask **"What's the current gold price?"**
+
+## Install by Client
+
+### Claude Desktop
+
+Add the block above to `claude_desktop_config.json`, then restart Claude Desktop.
+
+### Cursor / Windsurf / Cline / VS Code
+
+Add the same `commoditypriceapi` block to that client's MCP server config file and restart the client.
+
+### Any other MCP client
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@commoditypriceapi/mcp"],
+  "env": {
+    "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
+  }
+}
+```
+
+## Tools
+
+| Tool                   | Endpoint                    | What it does                                                    |
+| ---------------------- | ---------------------------- | ----------------------------------------------------------------|
+| `get_usage`            | `GET /v2/usage`              | Current plan, quota, and usage                                  |
+| `list_symbols`         | `GET /v2/symbols`            | All supported commodity symbols with category/currency/unit     |
+| `get_latest_rates`     | `GET /v2/rates/latest`       | Latest rates for one or more symbols                            |
+| `get_gold_price`       | `GET /v2/rates/latest/xau`   | Shortcut for the latest gold rate                                |
+| `get_silver_price`     | `GET /v2/rates/latest/xag`   | Shortcut for the latest silver rate                              |
+| `get_historical_rates` | `GET /v2/rates/historical`   | OHLC rates for one or more symbols on a specific past date       |
+| `get_time_series`      | `GET /v2/rates/time-series`  | Daily rates between two dates (max 1 year span)                  |
+| `get_fluctuation`      | `GET /v2/rates/fluctuation`  | Start/end rate, change, and % change over a date range           |
+
+All tools that take `symbols` accept a comma-separated list (e.g. `XAU,XAG,BRENTOIL`). Use `list_symbols` to look up valid symbols.
+
+## Authentication
+
+The server sends your API key to CommodityPriceAPI via **both** the `x-api-key` header and the `apiKey` query parameter — the upstream API accepts either, so this covers all cases without extra config.
+
+| Variable                 | Required | Description                       |
+| ------------------------ | -------- | ---------------------------------- |
+| `COMMODITYPRICEAPI_KEY`  | Yes      | Your CommodityPriceAPI key         |
+| `COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS` | No | Upstream request timeout in ms (default `15000`) |
+
+## Error Handling
+
+Tool calls never crash the server. Upstream errors (invalid symbol, missing date, quota exceeded, etc.) are returned as structured tool results with `error`, `code`, `message`, and a `guidance` field so the client can explain what went wrong instead of just echoing a status code.
+
+## Building from Source
+
+```bash
+git clone https://github.com/commoditypriceapi/commoditypriceapi-mcp.git
+cd commoditypriceapi-mcp
+npm install
+npm run build
+```
+
+Run it directly:
+
+```bash
+COMMODITYPRICEAPI_KEY=<YOUR_KEY> node dist/cli.js
+```
+
+Inspect with the MCP Inspector:
+
+```bash
+COMMODITYPRICEAPI_KEY=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/cli.js
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr only — stdout is reserved for the MCP protocol stream.
+    console.error("commoditypriceapi-mcp server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error starting commoditypriceapi-mcp server:", err);
+    process.exit(1);
+});

package/dist/client.js

@@ -0,0 +1,70 @@
+const BASE_URL = "https://api.commoditypriceapi.com/v2";
+export class CommodityApiError extends Error {
+    code;
+    errorType;
+    path;
+    constructor(code, errorType, message, path) {
+        super(message);
+        this.name = "CommodityApiError";
+        this.code = code;
+        this.errorType = errorType;
+        this.path = path;
+    }
+}
+function getApiKey() {
+    const key = process.env.COMMODITYPRICEAPI_KEY;
+    if (!key) {
+        throw new Error("COMMODITYPRICEAPI_KEY is not set. Add it to your MCP client config's env block.");
+    }
+    return key;
+}
+/**
+ * Calls a CommodityPriceAPI v2 endpoint.
+ * Sends the API key via both the x-api-key header AND the apiKey query
+ * param, since the upstream API accepts either.
+ */
+export async function callCommodityApi(path, params = {}) {
+    const apiKey = getApiKey();
+    const url = new URL(BASE_URL + path);
+    url.searchParams.set("apiKey", apiKey);
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== "") {
+            url.searchParams.set(key, value);
+        }
+    }
+    const timeoutMs = Number(process.env.COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS ?? 15000);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetch(url.toString(), {
+            method: "GET",
+            headers: {
+                "x-api-key": apiKey,
+                accept: "application/json",
+            },
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new CommodityApiError(499, "REQUEST_TIMEOUT", `Request to CommodityPriceAPI timed out after ${timeoutMs}ms.`);
+        }
+        throw new CommodityApiError(502, "UPSTREAM_UNREACHABLE", `Could not reach CommodityPriceAPI: ${err.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const text = await response.text();
+    let body;
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new CommodityApiError(response.status, "INVALID_RESPONSE", `CommodityPriceAPI returned a non-JSON response: ${text.slice(0, 500)}`);
+    }
+    if (!response.ok) {
+        throw new CommodityApiError(response.status, body.error ?? "UNKNOWN_ERROR", body.message ?? `CommodityPriceAPI request failed with status ${response.status}.`, body.path);
+    }
+    return body;
+}

package/dist/index.js

@@ -0,0 +1 @@
+export { createServer } from "./server.js";

package/dist/server.js

@@ -0,0 +1,209 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { callCommodityApi, CommodityApiError } from "./client.js";
+const symbolsParam = z
+    .string()
+    .describe("Comma-separated commodity symbols, e.g. 'XAU,XAG,BRENTOIL'. See the list_symbols tool for valid values.");
+const dateParam = z.string().describe("Date in YYYY-MM-DD format.");
+function textResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+function errorResult(err) {
+    if (err instanceof CommodityApiError) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: err.errorType,
+                        code: err.code,
+                        message: err.message,
+                        guidance: guidanceFor(err.code, err.errorType),
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error: "UNEXPECTED_ERROR", message: err.message }, null, 2),
+            },
+        ],
+    };
+}
+function guidanceFor(code, errorType) {
+    switch (code) {
+        case 401:
+            return "Check that COMMODITYPRICEAPI_KEY is set correctly in your MCP client config.";
+        case 402:
+            return "Your trial or subscription doesn't cover this request. Check your plan on the CommodityPriceAPI dashboard.";
+        case 403:
+            return "You've hit your API key's usage limit. Upgrade your plan or wait for the quota to reset.";
+        case 404:
+            if (errorType === "SYMBOL_NOT_FOUND") {
+                return "Call list_symbols to see valid commodity symbols.";
+            }
+            return "The requested resource was not found.";
+        case 429:
+            return "You're being rate limited. Wait a minute and try again.";
+        default:
+            return "CommodityPriceAPI returned an error outside the documented cases; treat the message above as authoritative.";
+    }
+}
+export function createServer() {
+    const server = new McpServer({
+        name: "commoditypriceapi-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("get_usage", {
+        title: "Get API usage",
+        description: "Returns the current plan, quota, and usage for the configured CommodityPriceAPI key.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const data = await callCommodityApi("/usage");
+            return textResult(data);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("list_symbols", {
+        title: "List supported commodity symbols",
+        description: "Returns all commodity symbols supported by CommodityPriceAPI, including category, default currency, and unit. Use this to look up a symbol before calling rate tools.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const data = await callCommodityApi("/symbols");
+            return textResult(data);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("get_latest_rates", {
+        title: "Get latest commodity rates",
+        description: "Returns the latest rates for one or more commodity symbols (e.g. gold, silver, crude oil). Rates may lag up to 10 minutes depending on plan. Use 'quote' to convert to a specific currency (Premium/Plus plans only).",
+        inputSchema: {
+            symbols: symbolsParam,
+            quote: z
+                .string()
+                .optional()
+                .describe("Target quote currency code (e.g. 'USD', 'EUR'). Premium/Plus plans only; omit to use each symbol's default currency."),
+        },
+    }, async ({ symbols, quote }) => {
+        try {
+            const data = await callCommodityApi("/rates/latest", { symbols, quote });
+            return textResult(data);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("get_gold_price", {
+        title: "Get latest gold (XAU) price",
+        description: "Shortcut for the latest gold (XAU) rate without needing to pass a symbols list.",
+        inputSchema: {
+            quote: z
+                .string()
+                .optional()
+                .describe("Target quote currency code. Premium/Plus plans only."),
+        },
+    }, async ({ quote }) => {
+        try {
+            const data = await callCommodityApi("/rates/latest/xau", { quote });
+            return textResult(data);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("get_silver_price", {
+        title: "Get latest silver (XAG) price",
+        description: "Shortcut for the latest silver (XAG) rate without needing to pass a symbols list.",
+        inputSchema: {
+            quote: z
+                .string()
+                .optional()
+                .describe("Target quote currency code. Premium/Plus plans only."),
+        },
+    }, async ({ quote }) => {
+        try {
+            const data = await callCommodityApi("/rates/latest/xag", { quote });
+            return textResult(data);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("get_historical_rates", {
+        title: "Get historical commodity rates",
+        description: "Returns open/high/low/close rates for one or more symbols on a specific past date (available back to 1990-01-01). If no rate exists for that exact date, the API returns the nearest available date.",
+        inputSchema: {
+            symbols: symbolsParam,
+            date: dateParam,
+        },
+    }, async ({ symbols, date }) => {
+        try {
+            const data = await callCommodityApi("/rates/historical", { symbols, date });
+            return textResult(data);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("get_time_series", {
+        title: "Get commodity time series",
+        description: "Returns daily historical rates for one or more symbols between two dates. The date range cannot exceed 1 year.",
+        inputSchema: {
+            symbols: symbolsParam,
+            startDate: dateParam,
+            endDate: dateParam,
+        },
+    }, async ({ symbols, startDate, endDate }) => {
+        try {
+            const data = await callCommodityApi("/rates/time-series", {
+                symbols,
+                startDate,
+                endDate,
+            });
+            return textResult(data);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("get_fluctuation", {
+        title: "Get commodity price fluctuation",
+        description: "Returns how one or more commodity symbols changed between a start and end date: start rate, end rate, absolute change, and percent change.",
+        inputSchema: {
+            symbols: symbolsParam,
+            startDate: dateParam,
+            endDate: dateParam,
+        },
+    }, async ({ symbols, startDate, endDate }) => {
+        try {
+            const data = await callCommodityApi("/rates/fluctuation", {
+                symbols,
+                startDate,
+                endDate,
+            });
+            return textResult(data);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@commoditypriceapi/mcp",
+  "version": "1.0.0",
+  "description": "Official MCP server for CommodityPriceAPI \u2014 real-time and historical commodity rates (gold, silver, oil, and 130+ more) as MCP tools for Claude, Cursor, Windsurf, and any MCP client.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "commodity-prices",
+    "gold-price",
+    "silver-price",
+    "commoditypriceapi",
+    "claude",
+    "ai-tools"
+  ],
+  "homepage": "https://commoditypriceapi.com",
+  "bugs": "https://github.com/commoditypriceapi/commoditypriceapi-mcp/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/commoditypriceapi/commoditypriceapi-mcp.git"
+  },
+  "license": "MIT",
+  "author": "CommodityPriceAPI",
+  "type": "module",
+  "bin": {
+    "commoditypriceapi-mcp": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc -p tsconfig.json --watch",
+    "start": "node dist/cli.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}