# Currency MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides currency conversion capabilities using the reliable [Frankfurter API](https://api.frankfurter.app/).

## Features

- **Real-time Exchange Rates**: Get current exchange rates for 31+ supported currencies
- **Historical Data**: Convert currencies using historical rates from specific dates
- **MCP Integration**: Seamlessly integrates with MCP-compatible AI tools and clients
- **No API Keys Required**: Free and reliable service with no authentication needed
- **Async Support**: Built with modern async Python for optimal performance
- **Input Validation**: Robust validation for currency codes, amounts, and dates

## Installation

### From PyPI
```bash
pip install currency-mcp
```

### From Source
```bash
git clone https://github.com/vanloc1808/currency-mcp.git
cd currency-mcp
uv sync
```

## Usage

### As a Standalone MCP Server

```bash
# Run the server directly
python currency_mcp_server.py

# Or use the installed package
currency-mcp
```

### In AI Tools and Editors

#### Claude (Anthropic)
1. **Install the package**:
   ```bash
   pip install currency-mcp
   ```

2. **Configure Claude** to use the MCP server:
   - In Claude's settings, add an MCP server configuration
   - **Name**: Currency Converter
   - **Command**: `python -m currency_mcp_server`
   - **Transport**: stdio

3. **Example questions to ask Claude**:
   - "Convert 500 USD to Japanese Yen"
   - "What was the exchange rate between EUR and GBP on March 15, 2024?"
   - "How much is 1000 CAD worth in Australian dollars?"
   - "Show me all the currencies you can convert between"
   - "What's the current rate for USD to Swiss Franc?"
   - "Convert 250 EUR to USD using today's rate"

#### Cursor
1. **Install the package**:
   ```bash
   pip install currency-mcp
   ```

2. **Configure Cursor** to use the MCP server:
   - Open Cursor settings
   - Navigate to AI settings
   - Add a new MCP server with:
     - **Name**: Currency Converter
     - **Command**: `python -m currency_mcp_server`
     - **Transport**: stdio

3. **Use in Cursor**:
   - Ask Cursor to convert currencies: "Convert 100 USD to EUR"
   - Request historical rates: "What was the USD to GBP rate on January 15, 2024?"
   - List available currencies: "Show me all supported currencies"

#### Zed
1. **Install the package**:
   ```bash
   pip install currency-mcp
   ```

2. **Configure Zed** to use the MCP server:
   - Open Zed preferences
   - Go to AI settings
   - Add MCP server configuration:
     - **Name**: Currency Converter
     - **Command**: `python -m currency_mcp_server`
     - **Transport**: stdio

3. **Use in Zed**:
   - Ask for currency conversions: "What's 200 USD in British Pounds?"
   - Get historical data: "Show me the EUR to USD rate from last week"
   - List currencies: "What currencies can you convert between?"

#### VSCode
1. **Install the package**:
   ```bash
   pip install currency-mcp
   ```

2. **Configure VSCode** to use the MCP server:
   - Install the MCP extension for VSCode
   - Add server configuration in settings.json:
   ```json
   {
     "mcp.servers": {
       "currency-converter": {
         "command": "python",
         "args": ["-m", "currency_mcp_server"],
         "transport": "stdio"
       }
     }
   }
   ```

3. **Use in VSCode**:
   - Ask the AI assistant for currency conversions
   - Request historical exchange rates
   - Get real-time currency information

### General MCP Usage

The currency MCP server can be used with any MCP-compatible client. Here are some common example questions you can ask:

#### Currency Conversion Questions
- "Convert 100 US dollars to euros"
- "What's 500 Canadian dollars worth in Japanese yen?"
- "How much is 1000 British pounds in Australian dollars?"
- "Convert 250 Swiss francs to US dollars"

#### Historical Rate Questions
- "What was the exchange rate between USD and EUR on January 15, 2024?"
- "Show me the GBP to USD rate from March 1st, 2024"
- "What was the EUR to JPY rate last week?"
- "Historical rate for CAD to USD on December 25, 2023"

#### Information Questions
- "What currencies can you convert between?"
- "Show me all supported currencies"
- "What's the current USD to EUR exchange rate?"
- "List all available currency pairs"

#### Complex Questions
- "If I have 1000 USD, how much would that be worth in EUR, GBP, and JPY?"
- "Compare the USD to EUR rate from January 2024 vs today"
- "What's the best time to convert USD to EUR based on recent rates?"

### Programmatic Usage

```python
from currency_mcp_server import mcp

# The server is now ready to handle MCP requests
# Use with any MCP-compatible client
```

## Available Tools

### `list_currencies`
Lists all supported currencies with their descriptions.

**Returns**: A list of 31+ currencies including USD, EUR, GBP, JPY, CAD, and more.

### `convert_currency`
Converts amounts between currencies with comprehensive support for:

- **Current rates**: Real-time exchange rates
- **Historical rates**: Date-specific conversions (YYYY-MM-DD format)
- **Input validation**: Ensures valid currency codes and amounts
- **Error handling**: Graceful fallbacks and informative error messages

**Parameters**:
- `amount`: The amount to convert (float)
- `from_code`: Source currency code (3-letter ISO code, e.g., "USD")
- `to_code`: Target currency code (3-letter ISO code, e.g., "EUR")
- `date`: Optional historical date in YYYY-MM-DD format

**Returns**: Conversion result with rate, converted amount, and effective date.

## Examples

### Basic Conversion
```python
# Convert 100 USD to EUR
result = await convert_currency(
    amount=100.0,
    from_code="USD",
    to_code="EUR"
)
# Result: 100 USD = 85.83 EUR (rate: 0.8583)
```

### Historical Conversion
```python
# Convert 50 USD to GBP on January 15, 2024
result = await convert_currency(
    amount=50.0,
    from_code="USD",
    to_code="GBP",
    date="2024-01-15"
)
# Result: 50 USD = 39.32 GBP (rate: 0.78643)
```

## Development

### Prerequisites
- Python 3.11+
- uv (recommended) or pip

### Setup
```bash
# Clone the repository
git clone https://github.com/vanloc1808/currency-mcp.git
cd currency-mcp

# Install dependencies
uv sync

# Run tests
python tests/client.py
```

### Testing
```bash
# Run the test client
python tests/client.py

# Or use the publishing scripts
./scripts/publish.sh uv test
```

## API Reference

The server uses the [Frankfurter API](https://api.frankfurter.app/) which provides:
- **No rate limits** for **reasonable** usage
- **31+ currencies** including major and minor pairs
- **Historical data** going back several years
- **Real-time rates** updated throughout the day

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Related

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
- [Frankfurter API](https://api.frankfurter.app/)
- [FastMCP](https://gofastmcp.com/)