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.

Item	Value
Package	@currencyfreaks/mcp
Transport	stdio
Node.js	>=18

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>"
      }
    }
  }
}

4. Restart your client.

5. 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:

Prompt	Expected tool
What's the current EUR to USD exchange rate?	get_latest_rates with symbols=EUR
Convert 500 USD to PKR.	convert_currency
What was 1,000 GBP worth in JPY on 2026-01-15?	convert_currency with date
What was the EUR/USD rate on January 2nd, 2020?	get_historical_rates
Show daily USD to INR rates for the first week of August 2026.	get_time_series
How much has the yen moved against the dollar since June 1st?	get_fluctuation
What's the currency code for the Nepalese rupee?	list_currencies with search=nepal
What's 50 USD in the local currency of IP 182.186.18.9?	ip_to_currency

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.

Parameter	Required	Description
search	No	Case-insensitive substring matched against code, name, or (with detailed) country name, e.g. rupee, PK, bitcoin
detailed	No	true returns country, status (AVAILABLE/DEPRECATED), the availableFrom/availableUntil historical data range, and flag icon per currency. Default false. Combine with search; the full detailed catalogue is ~270 KB.

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.

Parameter	Required	Description
symbols	No	Comma-separated currency codes. Omit for all 1000+ currencies.
base	No	Base currency code. Default USD. Paid plans only.

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.

Parameter	Required	Description
from	Yes	Currency code to convert from
to	Yes	Currency code to convert to
amount	No	Amount to convert, greater than 0. Default 1.0.
date	No	YYYY-MM-DD. Converts at that day's rate instead of the latest.

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.

Parameter	Required	Description
date	Yes	YYYY-MM-DD
symbols	No	Comma-separated currency codes. Omit for all.
base	No	Base currency code. Default USD.

get_time_series

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

Parameter	Required	Description
startDate	Yes	YYYY-MM-DD
endDate	Yes	YYYY-MM-DD
symbols	No	Comma-separated currency codes
base	No	Base currency code. Default USD.

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).

Parameter	Required	Description
startDate	Yes	YYYY-MM-DD
endDate	No	YYYY-MM-DD. Defaults to the day before today.
symbols	No	Comma-separated currency codes
base	No	Base currency code. Default USD.

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.

Parameter	Required	Description
from	Yes	Currency code to convert from
ip	No	IPv4 or IPv6 address. Omit to use the caller's own IP.
amount	No	Amount to convert. Default 1.0.

Plan Requirements

Feature	Minimum plan
list_currencies	None (no API key needed)
get_latest_rates with default USD base	Developer (free)
base parameter on any tool	Starter
convert_currency	Starter
get_historical_rates	Starter
ip_to_currency	Growth
get_time_series	Professional
get_fluctuation	Professional

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.

Code	Meaning
400	Missing API key, or invalid parameters (bad currency code, date format, amount, or IP address)
401	API key is invalid or inactive — check CURRENCYFREAKS_API_KEY in your client config
402	Feature not included in the current plan — see Plan Requirements
404	Rates not found for the requested currency, date, or interval
429	Monthly request quota exhausted — upgrade or wait for the reset
499	Request to the upstream API timed out (see CURRENCYFREAKS_REQUEST_TIMEOUT_MS)
502	Server could not reach the upstream API

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 [email protected]]",
  "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

Variable	Required	Default	Description
CURRENCYFREAKS_API_KEY	Yes		Your CurrencyFreaks API key
CURRENCYFREAKS_REQUEST_TIMEOUT_MS	No	15000	Upstream request timeout in ms

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