CurrencyFreaks

CurrencyFreaks MCP Server

Official MCP server for CurrencyFreaks. Exposes 7 MCP tools for real-time and historical exchange rates and currency conversion across 1000+ fiat currencies, cryptocurrencies, and precious metals. Your AI assistant asks for rates in plain English; the MCP server handles the API calls.

Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Cline, Codex, and any other MCP-compatible client.

Quick Start

1. Get a free CurrencyFreaks API key — 1,000 requests a month, no card required.

2. Cursor users can install in one click:

3. Everyone else: add this to your MCP client config (see Install by Client for the exact file path):

{
  "mcpServers": {
    "currencyfreaks": {
      "command": "npx",
      "args": ["-y", "@currencyfreaks/mcp"],
      "env": {
        "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

1. Restart your client.
2. Test it: ask "What's the current EUR to USD exchange rate?"

Table of Contents

• Quick Start
• Install by Client
• Verify It Works
• Tool Reference
• Plan Requirements
• Prompt Examples
• Example Answers and Tool Output
• Error Codes
• How It Works
• Environment Variables
• Building from Source
• Troubleshooting
• Pricing
• Links
• License

Install by Client

Requirements

• Node.js 18 or later
• npx available in your terminal
• A CurrencyFreaks API key — sign up free

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "currencyfreaks": {
      "command": "npx",
      "args": ["-y", "@currencyfreaks/mcp"],
      "env": {
        "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

claude mcp add currencyfreaks --env CURRENCYFREAKS_API_KEY=<YOUR_API_KEY> -- npx -y @currencyfreaks/mcp

Start a new Claude Code session after adding the server.

Cursor

One-click install:

Or add to .cursor/mcp.json manually:

{
  "mcpServers": {
    "currencyfreaks": {
      "command": "npx",
      "args": ["-y", "@currencyfreaks/mcp"],
      "env": {
        "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Restart Cursor after saving.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "currencyfreaks": {
      "command": "npx",
      "args": ["-y", "@currencyfreaks/mcp"],
      "env": {
        "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Restart Windsurf after saving.

VS Code / GitHub Copilot

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "currencyfreaks": {
        "command": "npx",
        "args": ["-y", "@currencyfreaks/mcp"],
        "env": {
          "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
        }
      }
    }
  }
}

Restart VS Code after saving.

Cline

Open MCP Servers panel → Configure → Advanced MCP Settings. Add to cline_mcp_settings.json:

{
  "mcpServers": {
    "currencyfreaks": {
      "command": "npx",
      "args": ["-y", "@currencyfreaks/mcp"],
      "env": {
        "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Restart Cline after saving.

Codex CLI

codex mcp add currencyfreaks --env CURRENCYFREAKS_API_KEY=<YOUR_API_KEY> -- npx -y @currencyfreaks/mcp
codex mcp list

Start a new Codex session after adding the server.

Any Other MCP Client

Use this config:

{
  "command": "npx",
  "args": ["-y", "@currencyfreaks/mcp"],
  "env": {
    "CURRENCYFREAKS_API_KEY": "<YOUR_API_KEY>"
  }
}

Verify It Works

Try these after setup:

Tool Reference

All 7 tools wrap the CurrencyFreaks v2.0 REST API. Tools that take symbols accept a comma-separated list of currency codes (e.g. EUR,GBP,PKR), case-insensitive. Use list_currencies to look up a code — there are 1000+ across fiat, crypto, and metals.

Precious metals use ISO 4217 codes: XAU (gold), XAG (silver), XPT (platinum), XPD (palladium). The API returns all rates and amounts as strings to preserve precision.

list_currencies

GET /v2.0/currency-symbols (compact) or GET /v2.0/supported-currencies (detailed) — the supported currency catalogue. No API key required.

get_latest_rates

GET /v2.0/rates/latest — latest rates for one or more currencies against a base. Refresh frequency depends on plan: daily on Developer (free), hourly on Starter, every 10 minutes on Growth, every 60 seconds on Professional and above.

convert_currency

GET /v2.0/convert/latest, or GET /v2.0/convert/historical when date is given — convert an amount between two currencies. Paid plans only.

get_historical_rates

GET /v2.0/rates/historical — rates on a specific past date. Major fiat currencies go back to 1984-11-28; newer currencies and crypto start from their own listing date. Paid plans only.

get_time_series

GET /v2.0/timeseries — daily rates between two dates, one entry per day. Professional plan and above.

get_fluctuation

GET /v2.0/fluctuation — how each currency moved between two dates: start rate, end rate, absolute change, and percent change. Professional plan and above.

Sign convention: change is startRate - endRate. A positive change means the rate fell (the symbol currency strengthened against the base); a negative change means the rate rose (the symbol currency weakened).

ip_to_currency

GET /v2.0/iptocurrency — resolves the local currency from an IP address's geolocation and converts an amount into it. The target currency comes back in the to field. Growth plan and above.

Plan Requirements

Calls that exceed the plan return a 402 error with guidance (see Error Codes).

Prompt Examples

Live rates

• What's the current EUR to USD exchange rate?
• Give me the latest rates for GBP, JPY, and CHF against the euro.
• What's bitcoin worth in USD right now?
• What's the gold price in euros?

Conversion

• Convert 250 USD to Indian rupees.
• How many yen is 1,200 euros?
• What was 500 GBP worth in USD on 2025-12-31?

Historical data

• What was the USD to PKR rate on January 2nd, 2020?
• Show me daily EUR/USD rates for Q1 2026.
• Compare the pound and the euro against the dollar over the last 30 days.

Price changes

• How much has the Turkish lira dropped against the dollar since January 1st?
• Did ETH go up or down versus USD this month, and by how much?

Discovery

• What's the currency code for the Kazakhstani tenge?
• Which currencies does CurrencyFreaks support for Africa?
• How far back does historical data go for the Nigerian naira?

Example Answers and Tool Output

The text answers show what a client might say; exact wording depends on the model. JSON blocks are raw tool output.

Latest rates

Prompt: What are the latest EUR, GBP, and PKR rates against the dollar?

Example answer: As of 2026-08-25 13:26 UTC, 1 USD buys 0.9279 EUR, 0.8173 GBP, or 281.62 PKR.

{
  "date": "2026-08-25 13:26:00+00",
  "base": "USD",
  "rates": {
    "EUR": "0.9278605451274349",
    "GBP": "0.8172754173817152",
    "PKR": "281.6212943333344",
    "USD": "1.0"
  }
}

Conversion

Prompt: Convert 500 USD to PKR.

Example answer: 500 USD is 140,841.48 PKR at a rate of 281.683.

{
  "date": "2026-08-25 15:22:00+00",
  "from": "USD",
  "to": "PKR",
  "rate": "281.683",
  "givenAmount": "500.0",
  "convertedAmount": "140841.475"
}

Fluctuation

Prompt: How did the Pakistani rupee move against the pound between June 1st and June 15th, 2026?

Example answer: PKR strengthened against the pound, going from 254.331 to 243.874 per GBP, a move of 10.457 (4.11%).

{
  "startDate": "2026-06-01",
  "endDate": "2026-06-15",
  "base": "GBP",
  "rateFluctuations": {
    "PKR": {
      "startRate": "254.331",
      "endRate": "243.874",
      "change": "10.457",
      "percentChange": "4.11"
    }
  }
}

Currency lookup

Prompt: What's the currency code for the Nepalese rupee?

Example answer: The Nepalese rupee is NPR.

{
  "count": 6,
  "currencies": {
    "SCR": "Seychellois Rupee",
    "MUR": "Mauritius Rupee",
    "INR": "Indian Rupee",
    "PKR": "Pakistani Rupee",
    "LKR": "Sri Lankan Rupee",
    "NPR": "Nepalese Rupee"
  }
}

Error Codes

Tool calls never crash the server. Upstream errors are returned as structured tool results with error, code, message, and a guidance field so the client can explain what went wrong instead of echoing a status code.

Example error result for an invalid key:

{
  "error": "Invalid Api Access Exception",
  "code": 401,
  "message": "Provided API key is invalid. [Contact tech. support for assistance at support@currencyfreaks.com]",
  "guidance": "The API key is invalid or inactive. Check CURRENCYFREAKS_API_KEY in your MCP client config and confirm the key is active on the CurrencyFreaks dashboard."
}

How It Works

This is a stdio MCP server that wraps the CurrencyFreaks v2.0 REST API.

At runtime:

1. Your MCP client starts the server process via npx.
2. The client reads the tool list.
3. When a prompt matches a tool, the client calls it.
4. The server validates inputs, calls CurrencyFreaks, and returns structured JSON.

The API key is read from the environment on each call and sent as the apikey query parameter. The catalogue endpoints behind list_currencies are public, so that tool works even before a key is configured.

Environment Variables

Building from Source

git clone https://github.com/CurrencyFreaks/currencyfreaks-mcp.git
cd currencyfreaks-mcp
npm install
npm run build

Run it directly:

CURRENCYFREAKS_API_KEY=<YOUR_KEY> node dist/cli.js

Inspect with the MCP Inspector:

CURRENCYFREAKS_API_KEY=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/cli.js

Troubleshooting

Client uses an old tool list after updating: Restart the client and confirm it loaded the latest npm version.

400 "Please provide API Key": CURRENCYFREAKS_API_KEY is not set in your MCP client config's env block.

401 errors: The key is wrong or inactive. Copy it again from the CurrencyFreaks dashboard.

402 errors: The tool needs a higher plan. See Plan Requirements. On the Developer (free) plan only get_latest_rates with the default USD base and list_currencies work.

404 "Rates of provided currency X are available from A to B": The date is outside that currency's data range. Call list_currencies with search=X and detailed=true to see availableFrom and availableUntil.

Huge responses: Always pass symbols to the rate tools and search to list_currencies. Without them the API returns all 1000+ currencies.

499 timeouts: The upstream API did not respond in time. Increase CURRENCYFREAKS_REQUEST_TIMEOUT_MS (default: 15000 ms).

Pricing

Developer plan is free with 1,000 requests a month, no card required. Paid plans add base currency selection, conversion, historical data, time series, fluctuation, and IP-to-currency, with faster refresh rates. See the CurrencyFreaks pricing page.

Links

• CurrencyFreaks Website
• API Documentation
• Supported Currencies
• Pricing
• Sign Up Free
• GitHub Repository

License

MIT