# MCP Server for Currency Exchange Rates

> Connect Claude Code, Cursor, VS Code, or Windsurf to live and historical exchange rates over MCP. Free plan, no credit card, 3,000 requests a month.

The Currency Exchange Rate API runs a remote Model Context Protocol (MCP) server, so an AI assistant can look up and convert exchange rates itself instead of guessing from stale training data. It exposes five read-only tools for current rates, conversions, historical rates, and time series across about 160 currencies. Setup is one command or one JSON snippet, with no local process to install.

## Endpoint and authentication

- Endpoint: https://api.currencyexchangerate-api.com/api/v1/mcp
- Transport: Streamable HTTP, stateless, JSON responses, POST only.
- Auth: `Authorization: Bearer <API key>`. Create a free key (no credit card) at https://currencyexchangerate-api.com/auth/login; manage keys at https://currencyexchangerate-api.com/app/keys.
- initialize, tools/list, and list_currencies need no API key, so an agent can discover the server first. The other four tools need a key sent as Authorization: Bearer <key>; keys start with cxr_. The server is stateless and answers with JSON over POST (Streamable HTTP); GET returns 405.

## Tools

| Tool | Arguments | Counts as a request | What it returns |
| --- | --- | --- | --- |
| `get_latest_rates` | `base?, symbols?` | Yes | Current rates per one unit of any base currency (default USD), with updatedAt and nextUpdateAt. |
| `convert_currency` | `from, to, amount?` | Yes | Converts an amount (default 1) at the current rate. |
| `get_historical_rates` | `date, base?, symbols?` | Yes | Closing rates for one past UTC day. Free plan: last 30 days; paid plans: back to 1999. |
| `get_rates_timeseries` | `start, end, base?, symbols?` | Yes | Daily closing rates from start to end inclusive, at most 366 days. |
| `list_currencies` | none | No | Every supported ISO 4217 code with its English name. |

Arguments marked with `?` are optional.

## Setup

### Claude Code

```shell
claude mcp add --transport http currency-rates https://api.currencyexchangerate-api.com/api/v1/mcp --header "Authorization: Bearer YOUR_API_KEY"
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "currency-rates": {
      "url": "https://api.currencyexchangerate-api.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "currency-rates": {
      "type": "http",
      "url": "https://api.currencyexchangerate-api.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:cxr-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "cxr-key",
      "description": "Currency Exchange Rate API key",
      "password": true
    }
  ]
}
```

### Windsurf

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

```json
{
  "mcpServers": {
    "currency-rates": {
      "serverUrl": "https://api.currencyexchangerate-api.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### curl (raw JSON-RPC)

```shell
# 1. Initialize (no key needed)
curl https://api.currencyexchangerate-api.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

# 2. List the tools (no key needed)
curl https://api.currencyexchangerate-api.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Convert 100 EUR to GBP (counts one request)
curl https://api.currencyexchangerate-api.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"convert_currency","arguments":{"from":"EUR","to":"GBP","amount":100}}}'
```

## Using the REST API from an AI coding assistant

Paste this into your assistant to have it write the integration:

```text
Add live exchange rates to this project with the Currency Exchange Rate API.
- Read https://currencyexchangerate-api.com/llms-full.txt for the full API reference, and https://currencyexchangerate-api.com/openapi.json for the OpenAPI description.
- Call the API from server-side code only, never from the browser. Read the API key from the environment variable CXR_API_KEY and send it as "Authorization: Bearer $CXR_API_KEY".
- Cache the GET /latest response until its nextUpdateAt timestamp instead of calling on every request.
- Do not hard-code the key or any exchange rate.
```

## FAQ

### Is the MCP server free?

Yes. The free plan includes 3,000 requests a month with no credit card, and it works with the MCP server. The free plan reaches historical rates back 30 days; paid plans reach back to 1999.

### Do I need an API key to discover the tools?

No. initialize, tools/list, and list_currencies work without a key. The four rate tools need one, and the error returned without a key says where to get it.

### Which MCP clients work?

The setup above covers Claude Code, Cursor, VS Code, and Windsurf. The server speaks standard Streamable HTTP, so a client that supports remote MCP servers over HTTP with custom headers can use the same endpoint and bearer header.

### Does it count against my request quota?

Each call to get_latest_rates, convert_currency, get_historical_rates, or get_rates_timeseries counts as one request against your monthly quota, shared with the REST API. Calls with invalid arguments are rejected before metering and cost nothing. list_currencies, initialize, and tools/list are never counted.

More: [API documentation](https://currencyexchangerate-api.com/docs), [full API reference](https://currencyexchangerate-api.com/llms-full.txt).