# Rate-API MCP Server

[![npm](https://img.shields.io/npm/v/@rate-api/mcp)](https://www.npmjs.com/package/@rate-api/mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

The official [Model Context Protocol](https://modelcontextprotocol.io) server for
[Rate-API.com](https://rate-api.com). It gives Claude and other MCP clients
exchange rates for 160+ currencies (updated hourly), currency conversion,
historical rates, daily time series and fluctuation, crypto, precious-metal and
end-of-day stock prices, usage and quota checks, and rate alerts.

Once connected, you can just ask: *"What's 250 EUR in Japanese yen?"* or
*"How has USD/TRY moved over the last 30 days?"* and the assistant calls the API
for you.

## Tools

| Tool | Description | Plan |
|------|-------------|------|
| `get_latest_rates` | Latest rates for a base currency (optionally filtered) | Free |
| `get_pair_rate` | Single currency-pair rate with optional precision (converted amount on Pro+) | Free |
| `list_currencies` | All supported currency codes and names | Free |
| `get_usage` | This key's plan and current-month usage against its quota | Free |
| `get_quota` | Plan quota and remaining requests for this key | Free |
| `get_key_status` | Confirm the key works (API status and version) | Free |
| `get_api_status` | Service status and data freshness | No key needed |
| `convert_currency` | Convert an amount between two currencies | Pro+ |
| `get_historical_rates` | Rates for a specific past date | Pro+ |
| `get_crypto_rates` | Cryptocurrency prices in USD | Pro+ |
| `get_metal_prices` | Gold, silver, platinum and palladium per troy ounce in USD | Pro+ |
| `get_stock_prices` | End-of-day closing prices for tracked equities in USD (indicative, not for trading) | Pro+ |
| `get_timeseries_rates` | Daily rates for every day between two dates (up to 366 days) | Business+ |
| `get_rate_fluctuation` | Start rate, end rate, change and % change between two dates (up to 366 days) | Business+ |
| `list_rate_alerts` | List the rate alerts on this key | Business+ |
| `create_rate_alert` | Alert (email and optional signed webhook) when a pair crosses a threshold | Business+ |
| `delete_rate_alert` | Delete a rate alert by id | Business+ |

"Pro+" means Pro, Business and Enterprise; "Business+" means Business and
Enterprise. Calling a tool your plan doesn't include returns the API's
`feature_not_available` error, so the assistant can tell you which plan it needs.
See [pricing](https://rate-api.com/pricing).

## Setup

You need an API key. The free plan (2,500 requests/month, no card) is at
<https://rate-api.com/register>; your keys are listed at <https://rate-api.com/api-keys>.

### Claude Code

```bash
claude mcp add rate-api -e RATE_API_KEY=YOUR_KEY -- npx -y @rate-api/mcp
```

### Claude Desktop / other MCP clients

Add to your MCP config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "rate-api": {
      "command": "npx",
      "args": ["-y", "@rate-api/mcp"],
      "env": { "RATE_API_KEY": "YOUR_KEY" }
    }
  }
}
```

### Run directly

```bash
RATE_API_KEY=YOUR_KEY npx -y @rate-api/mcp
```

### Docker

```bash
docker build -t rate-api-mcp .
docker run -i --rm -e RATE_API_KEY=YOUR_KEY rate-api-mcp
```

## Configuration

| Env var | Required | Default | Description |
|---------|----------|---------|-------------|
| `RATE_API_KEY` | for keyed tools | — | Your Rate-API key |
| `RATE_API_BASE_URL` | no | `https://rate-api.com` | Override the API base URL |
| `RATE_API_TIMEOUT_MS` | no | `15000` | Per-request timeout (ms) |

The server starts without a key; every tool except `get_api_status` then asks you
to set `RATE_API_KEY`.

## Resources & prompts

Besides the tools, the server exposes:
- **Resource** `rate-api://currencies`: the supported currency list (code, name, symbol, decimals).
- **Prompts** `convert_amount` and `currency_movement`: ready-made FX workflow templates.

## Local development

```bash
git clone https://github.com/Vilgar/rate-api-mcp.git
cd rate-api-mcp
npm install
RATE_API_KEY=YOUR_KEY npm start
# or inspect interactively:
RATE_API_KEY=YOUR_KEY npm run inspect
```

Transport is stdio; requires Node.js 18+. The only dependency is the official
`@modelcontextprotocol/sdk`.

## Links

- API docs: <https://rate-api.com/docs/api>
- OpenAPI 3.0: <https://rate-api.com/openapi.json>
- Issues: <https://github.com/Vilgar/rate-api-mcp/issues>

## License

MIT, see [LICENSE](LICENSE).