currency-mcp 0.3.0

A Model Context Protocol (MCP) server for currency conversion using the Frankfurter API

Currency MCP Server

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

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

pip install currency-mcp

From Source

git clone https://github.com/vanloc1808/currency-mcp.git
cd currency-mcp
uv sync

Usage

As a Standalone MCP Server

# 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:

   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:

   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:

   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:

   pip install currency-mcp
   

2. Configure VSCode to use the MCP server:

   • Install the MCP extension for VSCode
   • Add server configuration in settings.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

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

# 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

# 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

# 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

# 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 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 file for details.

Related

• Model Context Protocol
• MCP Servers Repository
• Frankfurter API
• FastMCP