# mcp-currencytransfer

MCP server for the [CurrencyTransfer API](https://stage.currencytransfer.com/api/v1/documentation.html). Lets AI assistants trade FX, manage beneficiaries, check balances, request quotes, and configure rate alerts, market orders and RSI alerts/market orders.

## Prerequisites

- [Node.js](https://nodejs.org/) 22 or newer (tested on Node 22 and 24 LTS)
- A CurrencyTransfer account with API credentials

## Setup

```bash
git clone https://github.com/currencytransfer/mcp-currencytransfer.git
cd mcp-currencytransfer
npm install
npm run build
```

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CT_API_KEY` | Yes | Your CurrencyTransfer account ID (Basic auth username) |
| `CT_API_SECRET` | Yes | Your CurrencyTransfer API key (Basic auth password) |
| `CT_ENV` | No | Which environment to connect to: `production`, `stage`, or `beta`. **Defaults to `stage`** so an incomplete config never acts on a live account. This is the preferred way to select an environment. |
| `CT_BASE_URL` | No | Advanced override of the full base URL. Wins over `CT_ENV`. A URL that isn't one of the three known environments is only accepted when `CT_DEV_MODE` is set (e.g. a local mock). Embedded credentials (`user:pass@host`) are always rejected. |
| `CT_DEV_MODE` | No | Set to `1` to permit loopback (`localhost`/`127.0.0.1`) and other non-standard `CT_BASE_URL` hosts for local development. Never set in production. |
| `CT_ENABLE_WRITES` | No | Set to `1` to expose mutating (financial write) tools. **Off by default** — the server ships read-only. |
| `CT_ENABLE_UNVERIFIED` | No | Set to `1` to expose RSI tools, whose routes are absent from the public API contract. Off by default. |

### Choosing an environment

Select the tier by name with `CT_ENV`:

| `CT_ENV` | Base URL |
|----------|----------|
| `production` | `https://app.currencytransfer.com/api/v1` |
| `stage` (default) | `https://stage.currencytransfer.com/api/v1` |
| `beta` | `https://beta.currencytransfer.com/api/v1` |

Each tier has its own credentials, so run **one server instance per environment**.
In your MCP host, add a separate entry per tier — e.g. "CurrencyTransfer (Prod)"
with `CT_ENV=production` and its production key, and "CurrencyTransfer (Stage)"
with `CT_ENV=stage` and its stage key. Don't try to switch tiers within a single
running server. On startup the server logs the resolved environment to stderr so a
prod/stage mix-up is immediately visible.

### Supported surface

By default the server registers only **read-only** tools. Financial write tools
(create/update/delete beneficiaries, payments, trades, quotes, alerts, top-ups) are
hidden and rejected unless `CT_ENABLE_WRITES=1`. RSI market-order tools are disabled
unless `CT_ENABLE_UNVERIFIED=1`. Disabled tools are absent from discovery *and*
rejected if invoked directly.

## MCP client configuration

This server uses **stdio** transport. Your MCP client will start it automatically — you do not need to run it in a terminal.

Add the following to your client's MCP config file. Most clients nest servers
under an `mcpServers` key; **VS Code's native `.vscode/mcp.json` uses `servers`
instead** (see the VS Code note below).

| Client | Config file | Top-level key |
|--------|-------------|---------------|
| Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json` | `mcpServers` |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) | `mcpServers` |
| VS Code | `.vscode/mcp.json` (native MCP support) | `servers` |
| Windsurf | `.windsurf/mcp_config.json` | `mcpServers` |

```json
{
  "mcpServers": {
    "currencytransfer": {
      "command": "node",
      "args": ["<git-repo-clone-location>/mcp-currencytransfer/dist/stdio.js"],
      "env": {
        "CT_API_KEY": "your-account-id",
        "CT_API_SECRET": "your-api-key",
        "CT_ENV": "stage"
      }
    }
  }
}
```

For **VS Code**, use `servers` instead of `mcpServers`:

```json
{
  "servers": {
    "currencytransfer": {
      "command": "node",
      "args": ["<git-repo-clone-location>/mcp-currencytransfer/dist/stdio.js"],
      "env": {
        "CT_API_KEY": "your-account-id",
        "CT_API_SECRET": "your-api-key"
      }
    }
  }
}
```

Restart your MCP client after saving the config. The server should then appear in the client's MCP settings or tool list.

## Tools

The server exposes tools for:

- **Currencies** — tradable pairs, RSI pairs, payment methods, cut-off times
- **Countries** — supported countries and payment methods
- **User** — authenticated user profile and permissions
- **Quotes** — FX quote requests
- **Trades** — create, list, and manage trades and documents
- **Beneficiaries** — manage payment beneficiaries
- **Balances** — account balances
- **Rate alerts** — standard and RSI (MOEX) rate alerts and market orders