# Wise Currency Converter MCP Server

A Model Context Protocol (MCP) server that provides currency conversion using the Wise API.

## Prerequisites

You need a Wise API key to use this server. Get your API key from [Wise API](https://api-docs.wise.com/).

## Features

- **Convert Currency**: Convert amounts between different currencies using real-time or historical Wise exchange rates
- **List Currencies**: Get a list of all supported currency codes
- **Rate Caching**: Built-in caching to minimize API calls
- **Cross-rate Calculation**: Automatic fallback to USD-based cross-rate calculation when direct rates are unavailable

## Installation

```bash
npm install
npm run build
```

## Configuration

### API Key Setup

Set your Wise API key as an environment variable:

```bash
export WISE_API_KEY="your-api-key-here"
```

Or copy the example environment file and add your key:

```bash
cp .env.example .env
# Edit .env and add your API key
```

**Security Note**: Never commit your API key to version control. The `.gitignore` file is configured to exclude `.env` files.

## Usage

### As an MCP Server

The server runs on stdio and can be used with any MCP client:

```bash
node dist/index.js
```

### Available Tools

#### 1. `convert_currency`

Converts an amount from one currency to another.

**Parameters:**
- `source_currency` (string, required): Source currency code (e.g., USD, EUR, GBP)
- `amount` (number, required): Amount to convert
- `target_currency` (string, required): Target currency code
- `date` (string, optional): Date for historical rate in YYYY-MM-DD format

**Example Response:**
```json
{
  "source_currency": "USD",
  "source_amount": 100,
  "target_currency": "EUR",
  "target_amount": 92.45,
  "exchange_rate": 0.9245,
  "date": "2024-01-15"
}
```

#### 2. `list_currencies`

Returns a list of all supported currency codes.

**Example Response:**
```json
{
  "currencies": ["USD", "EUR", "GBP", "JPY", ...],
  "total": 40
}
```

## Configuration with Claude Desktop

To use this MCP server with Claude Desktop, add it to your config file:

### macOS
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wise-currency": {
      "command": "node",
      "args": ["/path/to/wise-currency-converter-mcp/dist/index.js"],
      "env": {
        "WISE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Windows
Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wise-currency": {
      "command": "node",
      "args": ["C:\\path\\to\\wise-currency-converter-mcp\\dist\\index.js"],
      "env": {
        "WISE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Supported Currencies

The server supports 40 major world currencies including:
- USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY, SEK, NZD
- MXN, SGD, HKD, NOK, KRW, TRY, RUB, INR, BRL, ZAR
- And 20 more...

## Testing

Test the server functionality:

```bash
# Run the test script
WISE_API_KEY="your-api-key" node test.js
```

## Development

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Watch for changes during development
npm run dev

# Run the server directly for testing
WISE_API_KEY="your-api-key" node dist/index.js
```

## Project Structure

```
wise-currency-converter-mcp/
├── src/
│   ├── index.ts         # MCP server implementation
│   ├── wise-client.ts   # Wise API client with caching
│   └── types.ts         # TypeScript type definitions
├── dist/                # Compiled JavaScript output
├── test.js             # Test script for validation
├── .env.example        # Example environment configuration
├── .gitignore          # Git ignore rules
├── package.json        # Node.js dependencies
└── tsconfig.json       # TypeScript configuration
```

## Architecture

- **TypeScript**: Full type safety and better IDE support
- **MCP SDK**: Official Model Context Protocol SDK for server implementation
- **Wise API**: Real-time and historical exchange rates
- **Caching**: 1-minute TTL cache to reduce API calls
- **Error Handling**: Graceful fallback to cross-rate calculation
- **Security**: API key stored in environment variables, sanitized error logging

## Troubleshooting

### API Key Issues
- Ensure your API key is correctly set in the environment
- Check that the API key has the necessary permissions for rate queries
- The server will warn if no API key is detected

### Connection Issues
- Verify the Wise API endpoint is accessible
- Check network connectivity
- Review error messages in the console output

## License

MIT