currencyfreaks-mcp
OfficialCurrencyFreaks 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 |
|
Transport |
|
Node.js |
|
Quick Start
Get a free CurrencyFreaks API key — 1,000 requests a month, no card required.
Cursor users can install in one click:
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>"
}
}
}
}Restart your client.
Test it: ask "What's the current EUR to USD exchange rate?"
Related MCP server: Frankfurter Forex MCP
Table of Contents
Install by Client
Requirements
Node.js 18 or later
npxavailable in your terminalA 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/mcpStart 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 listStart 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? |
|
Convert 500 USD to PKR. |
|
What was 1,000 GBP worth in JPY on 2026-01-15? |
|
What was the EUR/USD rate on January 2nd, 2020? |
|
Show daily USD to INR rates for the first week of August 2026. |
|
How much has the yen moved against the dollar since June 1st? |
|
What's the currency code for the Nepalese rupee? |
|
What's 50 USD in the local currency of IP 182.186.18.9? |
|
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 |
| No | Case-insensitive substring matched against code, name, or (with |
| No |
|
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 |
| No | Comma-separated currency codes. Omit for all 1000+ currencies. |
| No | Base currency code. Default |
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 |
| Yes | Currency code to convert from |
| Yes | Currency code to convert to |
| No | Amount to convert, greater than 0. Default |
| No |
|
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 |
| Yes |
|
| No | Comma-separated currency codes. Omit for all. |
| No | Base currency code. Default |
get_time_series
GET /v2.0/timeseries — daily rates between two dates, one entry per day. Professional plan and above.
Parameter | Required | Description |
| Yes |
|
| Yes |
|
| No | Comma-separated currency codes |
| No | Base currency code. Default |
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 |
| Yes |
|
| No |
|
| No | Comma-separated currency codes |
| No | Base currency code. Default |
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 |
| Yes | Currency code to convert from |
| No | IPv4 or IPv6 address. Omit to use the caller's own IP. |
| No | Amount to convert. Default |
Plan Requirements
Feature | Minimum plan |
| None (no API key needed) |
| Developer (free) |
| Starter |
| Starter |
| Starter |
| Growth |
| Professional |
| 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 |
| Missing API key, or invalid parameters (bad currency code, date format, amount, or IP address) |
| API key is invalid or inactive — check |
| Feature not included in the current plan — see Plan Requirements |
| Rates not found for the requested currency, date, or interval |
| Monthly request quota exhausted — upgrade or wait for the reset |
| Request to the upstream API timed out (see |
| 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 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:
Your MCP client starts the server process via
npx.The client reads the tool list.
When a prompt matches a tool, the client calls it.
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 |
| Yes | Your CurrencyFreaks API key | |
| No |
| Upstream request timeout in ms |
Building from Source
git clone https://github.com/CurrencyFreaks/currencyfreaks-mcp.git
cd currencyfreaks-mcp
npm install
npm run buildRun it directly:
CURRENCYFREAKS_API_KEY=<YOUR_KEY> node dist/cli.jsInspect with the MCP Inspector:
CURRENCYFREAKS_API_KEY=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/cli.jsTroubleshooting
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
License
Available Tools
7 toolsconvert_currencyConvert an amount between currenciesA
Converts an amount from one currency to another using the latest rate, or the rate on a past date if 'date' is given. Returns the rate used, the given amount, and the converted amount. Starter plan and above (any paid plan).
Inputs: to (required), from (required), date, amount.
get_fluctuationGet exchange rate fluctuationA
Returns how currencies moved between two dates: start rate, end rate, absolute change, and percent change for each symbol against the base. Note the sign convention: change = startRate - endRate, so a POSITIVE change means fewer units per base, i.e. the symbol currency strengthened against the base, and a NEGATIVE change means the rate rose and the symbol currency weakened. Professional plan and above.
Inputs: startDate (required), base, endDate, symbols.
get_historical_ratesGet historical exchange ratesA
Returns exchange rates for a specific past date. Major fiat currencies go back to 1984-11-28; newer currencies and crypto start from their own listing date (see list_currencies with detailed=true). Starter plan and above (any paid plan).
Inputs: date (required), base, symbols.
get_latest_ratesGet latest exchange ratesA
Returns the latest exchange rates for one or more currencies against a base currency (USD by default). Covers fiat, crypto, and metals. Rates are returned as strings; refresh frequency depends on the plan (daily on Developer/free, hourly on Starter, every 10 minutes on Growth, every 60 seconds on Professional). Omit 'symbols' to get all 1000+ currencies.
Inputs: base, symbols.
get_time_seriesGet daily exchange rate time seriesB
Returns daily exchange rates for one or more currencies between two dates, one entry per day. Professional plan and above.
Inputs: endDate (required), startDate (required), base, symbols.
ip_to_currencyConvert to the local currency of an IP addressA
Resolves the local currency from an IP address's geolocation and converts an amount into it using the latest rate. Useful for localizing prices for a visitor. The target currency is returned in the 'to' field. Growth plan and above.
Inputs: from (required), ip, amount.
list_currenciesList supported currenciesA
Returns the currencies supported by CurrencyFreaks: 1000+ fiat currencies, cryptocurrencies, and precious metals (XAU gold, XAG silver, XPT platinum, XPD palladium). Use it to find a currency code before calling rate or conversion tools. No API key needed. By default returns a compact code → name map. Pass 'search' to filter by code, name, or country (e.g. 'rupee', 'PK', 'bitcoin'). Pass detailed=true for country, status (AVAILABLE/DEPRECATED), and the availableFrom/availableUntil date range of historical data per currency — combine with 'search' because the full detailed catalogue is very large.
Inputs: search, detailed.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct temporal or functional aspect (latest vs historical vs time series vs fluctuation vs conversion), and descriptions clarify boundaries. Slight overlap between get_latest_rates and convert_currency exists, but the conversion tool's added value (amount + rate + result) is clear.
Most tools follow a clean snake_case verb_noun pattern (list_currencies, get_latest_rates, convert_currency, get_historical_rates, get_time_series, get_fluctuation). ip_to_currency breaks the pattern as noun-first, a minor deviation.
Seven tools cleanly cover the currency-freaks API surface without bloat; each maps to a distinct endpoint/operation.
Covers catalogue lookup, latest/historical/time-series rates, conversion, fluctuation, and IP localization, matching the API's core lifecycle. Minor gaps like account/usage status or symbol-level metadata beyond list_currencies are non-critical.
Maintenance
Related MCP Connectors
Unofficial Exchange MCP — wraps the Frankfurter currency exchange API (free, no auth)
Unofficial Frankfurter MCP — wraps Frankfurter API (api.frankfurter.dev)
ExchangeRate MCP — wraps open.er-api.com (free, no auth)
Related MCP Servers
- FlicenseCqualityDmaintenanceAn MCP server providing real-time currency conversion and exchange rate data through the Frankfurter API, enabling users to convert currencies, fetch latest or historical rates, and list available currencies.437-
- FlicenseBqualityDmaintenanceAn MCP server that provides currency rates, conversions, and historical exchange-rate data using the Frankfurter API. It enables users to retrieve latest rates, convert amounts between currencies, and access time-series data for currency pairs.3-
- AlicenseAqualityBmaintenanceProvides real-time foreign-exchange rates, historical data, and multi-currency lookups to MCP-compatible AI coding assistants like Claude Code and Cursor.4MIT
- AlicenseAqualityCmaintenanceAn MCP server for the Xe Currency Data API that brings live FX rates, historical analysis, and quant-flavored tools into AI tools, working out of the box with zero credentials via Frankfurter/ECB data.123 npm1MIT