convert_currency

Convert monetary amounts between currencies using accurate exchange rates from the Frankfurter Forex MCP server. Enter amount, source currency, and target currency to get converted value.

Instructions

Convert a monetary amount from one currency to another.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`amount`	Yes
`from_currency`	Yes
`to_currency`	Yes

Implementation Reference

src/frankfurter_forex_mcp/tools/convert_currency.py:9-38 (handler)

The main handler function that executes the currency conversion logic. It calls the FrankfurterClient.convert method, validates the response payload, extracts the conversion rate, and returns a ConvertCurrencyOutput with the original amount, currencies, converted amount, and date.

async def execute(
    input_data: ConvertCurrencyInput,
    client: FrankfurterClient,
) -> ConvertCurrencyOutput:
    payload = await client.convert(
        amount=float(input_data.amount),
        source_currency=input_data.from_currency,
        destination_currency=input_data.to_currency,
    )
    rates = payload.get("rates", {})
    payload_date = payload.get("date")

    if not isinstance(rates, dict):
        raise FrankfurterClientError("Frankfurter API returned malformed rates payload")
    if not isinstance(payload_date, str):
        raise FrankfurterClientError("Frankfurter API returned malformed date payload")

    converted_amount = rates.get(input_data.to_currency)
    if converted_amount is None:
        raise FrankfurterClientError(
            "Frankfurter API returned no conversion rate for target currency"
        )

    return ConvertCurrencyOutput(
        original_amount=float(input_data.amount),
        source_currency=input_data.from_currency,
        destination_currency=input_data.to_currency,
        converted_amount=float(converted_amount),
        date=date.fromisoformat(payload_date),
    )

src/frankfurter_forex_mcp/models/schemas.py:54-75 (schema)

Pydantic schema definitions for convert_currency. ConvertCurrencyInput (lines 54-67) validates amount (PositiveFloat), from_currency, and to_currency (3-letter ISO 4217 codes with normalization). ConvertCurrencyOutput (lines 70-75) defines the response structure with original_amount, source_currency, destination_currency, converted_amount, and date.

class ConvertCurrencyInput(BaseModel):
    model_config = ConfigDict(populate_by_name=True, str_strip_whitespace=True)

    amount: PositiveFloat
    from_currency: str = Field(alias="from", min_length=3, max_length=3)
    to_currency: str = Field(alias="to", min_length=3, max_length=3)

    @field_validator("from_currency", "to_currency")
    @classmethod
    def normalize_currency(cls, value: str) -> str:
        value = _normalize_currency(value)
        if len(value) != 3 or not value.isalpha():
            raise ValueError("currency must be a 3-letter ISO 4217 code")
        return value


class ConvertCurrencyOutput(BaseModel):
    original_amount: float
    source_currency: str
    destination_currency: str
    converted_amount: float
    date: date

src/frankfurter_forex_mcp/server.py:48-69 (registration)

The tool registration function decorated with @mcp.tool(name="convert_currency"). It creates a ConvertCurrencyInput from the raw parameters, creates a FrankfurterClient, calls convert_currency.execute, and handles ValidationError, FrankfurterClientError, and unexpected exceptions with appropriate error responses.

@mcp.tool(name="convert_currency")
async def convert_currency_tool(amount: float, from_currency: str, to_currency: str) -> dict:
    """Convert a monetary amount from one currency to another."""
    try:
        input_data = ConvertCurrencyInput(
            amount=amount,
            from_currency=from_currency,
            to_currency=to_currency,
        )
        async with FrankfurterClient.from_env() as client:
            output = await convert_currency.execute(input_data, client)
        return output.model_dump(mode="json")
    except ValidationError as exc:
        return _to_error(str(exc), tool="convert_currency", error_code="validation_error")
    except FrankfurterClientError as exc:
        return _to_error(str(exc), tool="convert_currency", error_code="upstream_error")
    except Exception:
        return _to_error(
            "Unexpected internal error",
            tool="convert_currency",
            error_code="internal_error",
        )

src/frankfurter_forex_mcp/client/frankfurter.py:57-68 (helper)

The FrankfurterClient.convert helper method that makes the actual HTTP request to the Frankfurter API's /latest endpoint with amount, from, and to parameters. It returns the JSON response payload containing the conversion rates and date.

async def convert(
    self,
    amount: float,
    source_currency: str,
    destination_currency: str,
) -> dict[str, Any]:
    params = {
        "amount": amount,
        "from": source_currency,
        "to": destination_currency,
    }
    return await self._request_json("/latest", params=params)

Frankfurter Forex MCP