# realtime-currency-exchange-mcp

Real-time currency exchange MCP server powered by the free [Frankfurter API](https://www.frankfurter.app/). No API key required.

**Transport:** stdio  |  **Runtime:** Node.js  |  **Data source:** European Central Bank

## Features

- **Live exchange rates** — get the latest rates for any currency pair
- **Currency conversion** — convert amounts between currencies in real time
- **Historical rates** — look up rates for any past date
- **Currency catalog** — list all 32 supported currencies with names

## Prerequisites

- [Node.js](https://nodejs.org/) 18+

## Setup

```bash
git clone git@github.com:Ethereal-Jay/realtime-currency-exchange-mcp.git
cd realtime-currency-exchange-mcp
npm install
```

The entry point is `index.js`. Run it with `node index.js` — it communicates via stdio.

## Harness configuration

Add the following to your MCP client config, replacing `/path/to/repo` with the absolute path to the cloned directory.

### opencode

`~/.opencode/opencode.json`:

```json
{
  "mcp": {
    "currency-exchange": {
      "type": "local",
      "command": ["node", "/path/to/repo/index.js"]
    }
  }
}
```

### Claude Code / Claude Desktop

`~/.claude/claude_desktop_config.json` or `~/.claude.json`:

```json
{
  "mcpServers": {
    "currency-exchange": {
      "command": "node",
      "args": ["/path/to/repo/index.js"]
    }
  }
}
```

### Cursor

`.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "currency-exchange": {
      "command": "node",
      "args": ["/path/to/repo/index.js"]
    }
  }
}
```

### Generic MCP client

```json
{
  "currency-exchange": {
    "transport": "stdio",
    "command": "node",
    "args": ["/path/to/repo/index.js"]
  }
}
```

Restart your harness after adding the config. Tools will appear as `currency-exchange_get_exchange_rates`, `currency-exchange_convert_currency`, etc.

## Tools

| Tool | Description |
|---|---|
| `get_exchange_rates` | Latest rates for a base currency |
| `convert_currency` | Convert an amount between two currencies |
| `list_currencies` | List all supported currency codes and names |
| `get_historical_rates` | Exchange rates for a specific past date |

Detailed tool parameters and usage patterns are in [AGENTS.md](AGENTS.md).

## API

All data comes from [Frankfurter](https://www.frankfurter.app/), a free foreign exchange API that tracks reference rates published by the European Central Bank. Rates are updated daily around 16:00 CET.

## License

ISC