What the freecurrencyapi MCP server does
freecurrencyapi is a currency exchange rate API that’s free for hobby and personal projects; commercial use needs a paid plan on currencyapi.com. It includes a hosted Model Context Protocol (MCP) server. Connect it once and your AI coding tool (Claude Code, Cursor, Codex, VS Code or any other MCP client) can fetch exchange rates as native tools. You don’t need an SDK, glue code or a local server process.
Your agent gets four tools: latest rates, historical rates back to 1999-01-01, the list of supported currencies, and your quota status. Use them to look up a rate while you code, generate test fixtures from real historical data, or have the agent check its quota before a batch of calls.
MCP server URL (streamable HTTP):
https://api.freecurrencyapi.com/mcp
Auth: send your API key in the apikey header. Every request needs it, including the MCP handshake and the tool listing. Create a free API key if you don’t have one yet. Clients that support MCP sign-in (OAuth) can sign in instead.
Set up in your client
Every snippet connects to the same hosted server over HTTP. The snippets that read FREECURRENCYAPI_KEY expect your key in that environment variable (for example export FREECURRENCYAPI_KEY=... in your shell profile), so the key stays out of config files you might commit. The Cursor, Codex and VS Code snippets follow each client’s documented format for remote MCP servers (checked October 2026); if a client changes its schema, its linked docs have the current one.
Claude Code
Run this in your terminal:
claude mcp add --transport http freecurrencyapi https://api.freecurrencyapi.com/mcp --header "apikey: YOUR_API_KEY"
Run claude mcp list to confirm the server is registered. Inside a session, /mcp shows its connection status.
Cursor
Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json to use it in every project (Cursor’s MCP docs):
{
"mcpServers": {
"freecurrencyapi": {
"url": "https://api.freecurrencyapi.com/mcp",
"headers": { "apikey": "${env:FREECURRENCYAPI_KEY}" }
}
}
}
Then open Cursor Settings → MCP and check that freecurrencyapi shows four tools.
Codex
Add this to ~/.codex/config.toml (Codex MCP docs). env_http_headers reads the header value from the environment variable:
[mcp_servers.freecurrencyapi]
url = "https://api.freecurrencyapi.com/mcp"
env_http_headers = { "apikey" = "FREECURRENCYAPI_KEY" }
Restart Codex so it loads the new server.
VS Code
Add this to .vscode/mcp.json in your workspace (VS Code MCP configuration reference). VS Code asks for the key when the server first starts and stores it securely, so it stays out of your repo:
{
"inputs": [
{
"type": "promptString",
"id": "freecurrencyapi-key",
"description": "freecurrencyapi API key",
"password": true
}
],
"servers": {
"freecurrencyapi": {
"type": "http",
"url": "https://api.freecurrencyapi.com/mcp",
"headers": { "apikey": "${input:freecurrencyapi-key}" }
}
}
}
Start the server from the MCP view, or use it from Copilot Chat in agent mode.
Any other MCP client
Most clients accept this shape:
{
"mcpServers": {
"freecurrencyapi": {
"url": "https://api.freecurrencyapi.com/mcp",
"headers": { "apikey": "YOUR_API_KEY" }
}
}
}
Tip: if a config file lives in a shared repo, keep your key out of it: use your client’s environment-variable or input mechanism, or keep the config at user level instead of project level.
Sign in instead of an API key
MCP clients that support sign-in (OAuth), such as Claude’s custom connectors, can sign in instead of sending a key. In Claude, open Settings → Connectors → Add custom connector and enter https://api.freecurrencyapi.com/mcp. The client opens a sign-in page on app.freecurrencyapi.com: sign in or sign up, and approve the connection (as the team’s owner or an admin). The client then holds a key of your team that lasts an hour and renews itself; its tool calls count against your plan like any other request. You can disconnect it at any time under API keys → Connected apps in the dashboard. For your own code, use an API key.
Available tools
Each tool maps one-to-one to a REST endpoint, so anything your agent does through MCP you can later reproduce in code with the same API.
| Tool | Endpoint | What it returns |
|---|---|---|
getLatest | GET /v1/latest | Latest end-of-day exchange rates for the 33 supported currencies; any of them can be the base currency (docs) |
getHistorical | GET /v1/historical | Daily exchange rates for a past date, back to 1999-01-01 (docs) |
getCurrencies | GET /v1/currencies | The list of supported currencies (docs) |
getStatus | GET /v1/status | Your account’s quota status (docs) |
Tool calls are metered like regular API requests; failed requests and validation errors don’t count against your quota. Errors come back in the same machine-readable format as the REST API, so your agent can tell whether to retry, fix its input or stop. For parameters and response formats, see the MCP documentation and the API documentation.
Example prompts
Once the server is connected, paste any of these into Claude Code, Cursor, Codex or VS Code:
- “What’s today’s EUR to USD rate? Use freecurrencyapi.”
- “Get the latest rates with GBP as the base currency and show JPY, CHF and CAD.”
- “What was the USD to EUR rate on 2008-09-15?”
- “List every currency freecurrencyapi supports and generate a TypeScript union type from the codes.”
- “Fetch the EUR rates for 2020-03-02 and write them to
fixtures/rates.jsonfor my unit tests.” - “Check my freecurrencyapi quota before you run anything else.”
- “Write a Python function that converts an amount between two currencies using the freecurrencyapi REST API. Check the response shape with a live call first.”
The last prompt is a useful pattern: the agent inspects real responses through MCP, then writes production code against the REST API or one of the official SDKs (PHP, Python, JavaScript, Ruby, Go, Rust, R).
Limits and data coverage
The MCP server uses the same data and the same plan as the REST API:
- Currencies: 33 major currencies, and any of them can be the base (full list)
- Updates: once a day (end-of-day rates)
- History: daily rates back to 1999-01-01, one date per request
- Free plan: 1,000 requests per month, 10 requests per minute, no payment required
- Usage: free for hobby and personal projects only
For commercial use, 170+ currencies, crypto and metals, date-range requests or rates updated every 60 seconds, use currencyapi.com. The same team runs both services.
Onboard your agent with agents.md
MCP gives your agent live tools; agents.md gives it context: how the API works, how to pass auth and which endpoints exist. Ask your coding agent to run curl -s https://freecurrencyapi.com/agents.md and follow it. With both, it has what it needs to write integration code against the API.
FAQ
What is a currency API MCP server?
It's an MCP endpoint that exposes a currency API's functions as tools an AI assistant can call directly. With freecurrencyapi's server, tools like Claude Code or Cursor can fetch latest and historical exchange rates without you writing HTTP or SDK code.
Which AI tools work with the freecurrencyapi MCP server?
Any MCP client that supports remote HTTP servers, with your key in a header or by signing in (OAuth). This page has setup for Claude Code, Cursor, Codex and VS Code, and for Claude's custom connectors, which sign in.
Is the MCP server free?
Yes, for hobby and personal projects. It's included in the free plan: 1,000 requests per month and 10 requests per minute. Commercial use needs a paid plan on currencyapi.com.
Do MCP tool calls count against my quota?
Yes. Tool calls are metered like regular API requests. Failed requests and validation errors don't count. Your agent can call getStatus to check your remaining quota.
Do I need an API key just to connect?
Not if your client supports MCP sign-in (OAuth), as Claude's custom connectors do: you sign in on app.freecurrencyapi.com and approve the connection instead. Otherwise every request needs your key in the apikey header, including the MCP handshake and the tool listing; without it, the client can't load the tools.
Do I have to run anything locally?
No. The server is hosted at https://api.freecurrencyapi.com/mcp. You only add the URL to your client, with your key or by signing in.
How current are the rates?
Rates update once a day (end-of-day rates). Historical daily rates go back to 1999-01-01. For rates updated every 60 seconds, use currencyapi.com.
Which currencies are supported?
33 major currencies, and any of them can be the base currency. Ask your agent to call getCurrencies, or see the currency list.
Can I get crypto or metal prices through MCP?
Not from freecurrencyapi. Crypto, metals and 170+ currencies are available on currencyapi.com.
Give your agent exchange rates, free for personal projects
Create a key and paste one snippet. Your agent then has latest and historical rates for 33 currencies, with 1,000 requests a month and no payment required. Commercial projects should use currencyapi.com.