MCP Currency Converter Server

https://github.com/wesbos/currency-conversion-mcp
Admin
An MCP server that provides real-time currency conversion and exchange rate data using the...
Tokens:4,967
Snippets:19
Trust Score:10
Update:11 months ago
Show doc for...
Tokens:
Raw
### Get Historical Exchange Rates Request Example

Source: https://github.com/wesbos/currency-conversion-mcp/blob/main/README.md

This JSON object demonstrates how to fetch historical exchange rates for a given date. Similar to the latest rates, it allows setting a base currency and filtering by symbols.

```json
{
  "date": "2024-01-01",
  "base": "EUR",
  "symbols": "USD,GBP"
}
```

--------------------------------

### Get Latest Exchange Rates Request Example

Source: https://github.com/wesbos/currency-conversion-mcp/blob/main/README.md

This JSON object shows how to request the latest exchange rates. It allows specifying a base currency and optionally filtering the results to a specific set of symbols (currencies).

```json
{
  "base": "USD",
  "symbols": "EUR,GBP,JPY"
}
```

--------------------------------

### Get Currencies

Source: https://github.com/wesbos/currency-conversion-mcp/blob/main/README.md

Retrieves a list of all available currencies supported by the API, along with their full names.

```APIDOC
## GET /mcp/currencies

### Description
Lists all available currencies with their full names.

### Method
GET

### Endpoint
https://currency-mcp.wesbos.com/mcp/currencies

### Parameters
#### Query Parameters
None

### Request Example
`GET /mcp/currencies`

### Response
#### Success Response (200)
- **currencies** (object) - An object where keys are currency codes and values are the full currency names.

#### Response Example
```json
{
  "currencies": {
    "EUR": "Euro",
    "USD": "United States Dollar",
    "GBP": "British Pound"
  }
}
```
```

--------------------------------

### Convert Currency Request Example

Source: https://github.com/wesbos/currency-conversion-mcp/blob/main/README.md

This JSON object represents a request to convert a specified amount from one currency to another. It includes the source currency, target currency, and the amount to be converted.

```json
{
  "from": "USD",
  "to": "EUR",
  "amount": 100
}
```

--------------------------------

### List Available Currencies (TypeScript)

Source: https://context7.com/wesbos/currency-conversion-mcp/llms.txt

Fetches a list of all currency codes and their corresponding full names supported by the Frankfurter API. This tool is useful for understanding the available currency options. It performs a simple GET request and returns the currency data or an error message if the request fails.

```typescript
const getCurrenciesSchema = {};

type GetCurrenciesInput = Record<string, never>;

async function getCurrencies(_input: GetCurrenciesInput): Promise<ToolResponse> {
  try {
    const url = "https://api.frankfurter.dev/v1/currencies";
    const response = await fetch(url);

    if (!response.ok) {
      return {
        content: [{
          type: "text",
          text: `Error: Unable to fetch currencies. Status: ${response.status}`,
        }],
      };
    }

    const data = await response.json();

    return {
      content: [{
        type: "text",
        text: JSON.stringify(data),
      }],
    };
  } catch (error) {
    return {
      content: [{
        type: "text",
        text: `Error: Failed to fetch currencies - ${error instanceof Error ? error.message : "Unknown error"}`,
      }],
    };
  }
}

// Example usage: List all available currencies
const currencies = await getCurrencies({});
// Returns: {"AUD":"Australian Dollar","BGN":"Bulgarian Lev","BRL":"Brazilian Real","CAD":"Canadian Dollar","CHF":"Swiss Franc",...}
```

--------------------------------

### Get Latest Rates

Source: https://github.com/wesbos/currency-conversion-mcp/blob/main/README.md

Fetches the latest exchange rates. You can specify a base currency and optionally filter by specific symbols.

```APIDOC
## GET /mcp/latest

### Description
Fetches the latest exchange rates.

### Method
GET

### Endpoint
https://currency-mcp.wesbos.com/mcp/latest

### Parameters
#### Query Parameters
- **base** (string) - Optional - Base currency code (defaults to EUR)
- **symbols** (string) - Optional - Comma-separated currency codes to limit results

### Request Example
`GET /mcp/latest?base=USD&symbols=EUR,GBP,JPY`

### Response
#### Success Response (200)
- **base** (string) - The base currency.
- **rates** (object) - An object containing currency codes as keys and their rates as values.

#### Response Example
```json
{
  "base": "USD",
  "rates": {
    "EUR": 0.9250,
    "GBP": 0.7900,
    "JPY": 145.00
  }
}
```
```

--------------------------------

### Deploy Currency Conversion MCP as Cloudflare Worker

Source: https://context7.com/wesbos/currency-conversion-mcp/llms.txt

This JSON configuration file (`wrangler.toml`) is used to deploy the MCP server as a Cloudflare Worker. It specifies the worker's name, main entry point, compatibility dates and flags, Durable Objects configuration for stateful connections, and enables observability. This setup allows for a scalable and robust currency conversion service.

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "currency-conversion-mcp",
  "main": "src/index.ts",
  "compatibility_date": "2025-04-01",
  "compatibility_flags": ["nodejs_compat", "nodejs_compat_populate_process_env"],
  "migrations": [
    {
      "new_sqlite_classes": ["MyMCP"],
      "tag": "v1"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "class_name": "MyMCP",
        "name": "MCP_OBJECT"
      }
    ]
  },
  "observability": {
    "enabled": true
  }
}
```

--------------------------------

### Get Historical Rates

Source: https://github.com/wesbos/currency-conversion-mcp/blob/main/README.md

Fetches historical exchange rates for a specific date. You can specify the date, base currency, and filter by symbols.

```APIDOC
## GET /mcp/historical/{date}

### Description
Gets historical exchange rates for a specific date.

### Method
GET

### Endpoint
https://currency-mcp.wesbos.com/mcp/historical/{date}

### Parameters
#### Path Parameters
- **date** (string) - Required - Date in YYYY-MM-DD format

#### Query Parameters
- **base** (string) - Optional - Base currency code (defaults to EUR)
- **symbols** (string) - Optional - Comma-separated currency codes to limit results

### Request Example
`GET /mcp/historical/2024-01-01?base=EUR&symbols=USD,GBP`

### Response
#### Success Response (200)
- **date** (string) - The requested date.
- **base** (string) - The base currency.
- **rates** (object) - An object containing currency codes as keys and their historical rates as values.

#### Response Example
```json
{
  "date": "2024-01-01",
  "base": "EUR",
  "rates": {
    "USD": 1.0950,
    "GBP": 0.8800
  }
}
```
```

--------------------------------

### Get Latest Exchange Rates (TypeScript)

Source: https://context7.com/wesbos/currency-conversion-mcp/llms.txt

Fetches the latest currency exchange rates from the Frankfurter API. It allows specifying a base currency and filtering by specific symbols. The function handles API requests, response parsing, and error handling, returning exchange rate data or an error message.

```typescript
const getLatestRatesSchema = {
  base: z.string().length(3).optional().describe("Base currency code (default: EUR)"),
  symbols: z.string().optional().describe("Comma-separated currency codes to limit results (e.g., USD,GBP,JPY)"),
};

type GetLatestRatesInput = {
  base?: string;
  symbols?: string;
};

async function getLatestRates(input: GetLatestRatesInput): Promise<ToolResponse> {
  const { base, symbols } = input;

  try {
    const params = new URLSearchParams();
    if (base) params.append("base", base.toUpperCase());
    if (symbols) params.append("symbols", symbols.toUpperCase());

    const url = `https://api.frankfurter.dev/v1/latest${params.toString() ? `?${params.toString()}` : ""}`;
    const response = await fetch(url);

    if (!response.ok) {
      return {
        content: [{
          type: "text",
          text: `Error: Unable to fetch exchange rates. Status: ${response.status}`,
        }],
      };
    }

    const data = await response.json();

    return {
      content: [{
        type: "text",
        text: JSON.stringify(data),
      }],
    };
  } catch (error) {
    return {
      content: [{
        type: "text",
        text: `Error: Failed to fetch exchange rates - ${error instanceof Error ? error.message : "Unknown error"}`,
      }],
    };
  }
}

// Example 1: Get all rates with EUR as base (default)
const allRates = await getLatestRates({});
// Returns: {"base":"EUR","date":"2024-01-15","rates":{"USD":1.09,"GBP":0.86,"JPY":156.23,...}}

// Example 2: Get specific rates with USD as base
const usdRates = await getLatestRates({ base: "USD", symbols: "EUR,GBP,JPY" });
// Returns: {"base":"USD","date":"2024-01-15","rates":{"EUR":0.92,"GBP":0.79,"JPY":143.45}}
```

--------------------------------

### Get Historical Exchange Rates (TypeScript)

Source: https://context7.com/wesbos/currency-conversion-mcp/llms.txt

Retrieves historical currency exchange rates for a specified date from the Frankfurter API. Supports setting a base currency and filtering by symbols. The function ensures correct date formatting and handles API communication, providing historical rate data or error feedback.

```typescript
const getHistoricalRatesSchema = {
  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("Date in YYYY-MM-DD format"),
  base: z.string().length(3).optional().describe("Base currency code (default: EUR)"),
  symbols: z.string().optional().describe("Comma-separated currency codes to limit results"),
};

type GetHistoricalRatesInput = {
  date: string;
  base?: string;
  symbols?: string;
};

async function getHistoricalRates(input: GetHistoricalRatesInput): Promise<ToolResponse> {
  const { date, base, symbols } = input;

  try {
    const params = new URLSearchParams();
    if (base) params.append("base", base.toUpperCase());
    if (symbols) params.append("symbols", symbols.toUpperCase());

    const url = `https://api.frankfurter.dev/v1/${date}${params.toString() ? `?${params.toString()}` : ""}`;
    const response = await fetch(url);

    if (!response.ok) {
      return {
        content: [{
          type: "text",
          text: `Error: Unable to fetch historical rates. Status: ${response.status}`,
        }],
      };
    }

    const data = await response.json();

    return {
      content: [{
        type: "text",
        text: JSON.stringify(data),
      }],
    };
  } catch (error) {
    return {
      content: [{
        type: "text",
        text: `Error: Failed to fetch historical rates - ${error instanceof Error ? error.message : "Unknown error"}`,
      }],
    };
  }
}

// Example: Get EUR rates for January 1, 2024
const historicalRates = await getHistoricalRates({
  date: "2024-01-01",
  base: "EUR",
  symbols: "USD,GBP"
});
// Returns: {"base":"EUR","date":"2024-01-01","rates":{"USD":1.10,"GBP":0.87}}
```

--------------------------------

### Initialize MCP Server with Currency Tools (TypeScript)

Source: https://context7.com/wesbos/currency-conversion-mcp/llms.txt

Initializes the MCP server and registers currency conversion tools like convert_currency, get_latest_rates, get_currencies, and get_historical_rates. The fetch handler routes requests to the appropriate transport endpoints (/sse or /mcp).

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { McpAgent } from "agents/mcp";

export class MyMCP extends McpAgent {
  server = new McpServer({
    name: "Currency Converter",
    version: "1.0.0",
  });

  async init() {
    this.server.tool("convert_currency", convertCurrencySchema, async (input) =>
      convertCurrency(input),
    );

    this.server.tool("get_latest_rates", getLatestRatesSchema, async (input) =>
      getLatestRates(input),
    );

    this.server.tool("get_currencies", getCurrenciesSchema, async (input) =>
      getCurrencies(input),
    );

    this.server.tool("get_historical_rates", getHistoricalRatesSchema, async (input) =>
      getHistoricalRates(input),
    );
  }
}

// Worker fetch handler routes requests to appropriate transport endpoints
export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const url = new URL(request.url);

    if (url.pathname === "/sse" || url.pathname === "/sse/message") {
      return MyMCP.serveSSE("/sse").fetch(request, env, ctx);
    }

    if (url.pathname === "/mcp") {
      return MyMCP.serve("/mcp").fetch(request, env, ctx);
    }

    return new Response("Not found", { status: 404 });
  },
};

```

--------------------------------

### MCP Server Initialization

Source: https://context7.com/wesbos/currency-conversion-mcp/llms.txt

Initializes the MCP server and registers currency conversion tools like convert_currency, get_latest_rates, get_currencies, and get_historical_rates.

```APIDOC
## MCP Server Initialization

### Description
Initialize the MCP server with currency conversion tools registered as callable methods. This includes setting up tools for currency conversion, fetching latest rates, listing available currencies, and retrieving historical rates.

### Method
POST (Implicit via tool registration)

### Endpoint
/mcp or /sse

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (Configuration is done via code)

### Request Example
```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { McpAgent } from "agents/mcp";

export class MyMCP extends McpAgent {
  server = new McpServer({
    name: "Currency Converter",
    version: "1.0.0",
  });

  async init() {
    this.server.tool("convert_currency", convertCurrencySchema, async (input) =>
      convertCurrency(input),
    );

    this.server.tool("get_latest_rates", getLatestRatesSchema, async (input) =>
      getLatestRates(input),
    );

    this.server.tool("get_currencies", getCurrenciesSchema, async (input) =>
      getCurrencies(input),
    );

    this.server.tool("get_historical_rates", getHistoricalRatesSchema, async (input) =>
      getHistoricalRates(input),
    );
  }
}

// Worker fetch handler routes requests to appropriate transport endpoints
export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const url = new URL(request.url);

    if (url.pathname === "/sse" || url.pathname === "/sse/message") {
      return MyMCP.serveSSE("/sse").fetch(request, env, ctx);
    }

    if (url.pathname === "/mcp") {
      return MyMCP.serve("/mcp").fetch(request, env, ctx);
    }

    return new Response("Not found", { status: 404 });
  },
};
```

### Response
#### Success Response (200)
Server initialization is a configuration step and does not directly return a response to an API call in this context. The `init` method configures the server to handle subsequent tool calls.

#### Response Example
N/A
```

--------------------------------

### Configure MCP Remote Client for Currency Conversion

Source: https://github.com/wesbos/currency-conversion-mcp/blob/main/README.md

This configuration demonstrates how to set up an MCP remote client to connect to the currency conversion server using the SSE endpoint. It specifies the command to run and the arguments required to connect to the provided URL.

```json
{
  "mcpServers": {
    "currency-conversion": {
      "command": "npx",
      "args": ["mcp-remote", "https://currency-mcp.wesbos.com/sse"]
    }
  }
}
```

--------------------------------

### Convert Currency Tool

Source: https://context7.com/wesbos/currency-conversion-mcp/llms.txt

Converts a specified amount from one currency to another using real-time exchange rates fetched from the Frankfurter API.

```APIDOC
## Convert Currency Tool

### Description
Convert an amount from one currency to another with automatic rate calculation and rounding. This tool fetches the latest exchange rate between the specified currencies and performs the conversion.

### Method
POST (Implicit via MCP tool invocation)

### Endpoint
/mcp or /sse (depending on transport protocol)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **from** (string) - Required - Source currency code (e.g., USD, EUR)
- **to** (string) - Required - Target currency code (e.g., USD, EUR)
- **amount** (number) - Required - Amount to convert. Must be a positive number.

### Request Example
```json
{
  "from": "USD",
  "to": "EUR",
  "amount": 100
}
```

### Response
#### Success Response (200)
- **content** (array) - Contains the result of the conversion.
  - **type** (string) - Always 'text'.
  - **text** (string) - A JSON string representing the conversion result, including base currency, date, rates, and conversion details.

#### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"base\":\"USD\",\"date\":\"2024-01-15\",\"rates\":{\"EUR\":0.92},\"conversion\":{\"from\":\"USD\",\"to\":\"EUR\",\"amount\":100,\"result\":92.00,\"rate\":0.92}}"
    }
  ]
}
```

#### Error Response
- **content** (array) - Contains an error message.
  - **type** (string) - Always 'text'.
  - **text** (string) - An error message indicating failure to fetch exchange rate or perform conversion.
```

--------------------------------

### Convert Currency Tool (TypeScript)

Source: https://context7.com/wesbos/currency-conversion-mcp/llms.txt

Defines the schema for currency conversion and implements the logic to convert an amount from a source currency to a target currency using the Frankfurter API. It handles potential API errors and returns the converted amount.

```typescript
import { z } from "zod";

const convertCurrencySchema = {
  from: z.string().length(3).describe("Source currency code (e.g., USD, EUR)"),
  to: z.string().length(3).describe("Target currency code (e.g., USD, EUR)"),
  amount: z.number().positive().describe("Amount to convert"),
};

type ConvertCurrencyInput = {
  from: string;
  to: string;
  amount: number;
};

async function convertCurrency(input: ConvertCurrencyInput): Promise<ToolResponse> {
  const { from, to, amount } = input;

  try {
    const url = `https://api.frankfurter.dev/v1/latest?base=${from.toUpperCase()}&symbols=${to.toUpperCase()}`;
    const response = await fetch(url);

    if (!response.ok) {
      return {
        content: [{
          type: "text",
          text: `Error: Unable to fetch exchange rate. Status: ${response.status}`,
        }],
      };
    }

    const data = await response.json();
    const rate = data.rates[to.toUpperCase()];
    const convertedAmount = Math.round(amount * rate * 100) / 100;

    const result = {
      ...data,
      conversion: {
        from: from.toUpperCase(),
        to: to.toUpperCase(),
        amount: amount,
        result: convertedAmount,
        rate: rate,
      },
    };

    return {
      content: [{
        type: "text",
        text: JSON.stringify(result),
      }],
    };
  } catch (error) {
    return {
      content: [{
        type: "text",
        text: `Error: Failed to convert currency - ${error instanceof Error ? error.message : "Unknown error"}`,
      }],
    };
  }
}

// Example usage: Convert 100 USD to EUR
const result = await convertCurrency({ from: "USD", to: "EUR", amount: 100 });
// Returns: {"base":"USD","date":"2024-01-15","rates":{"EUR":0.92},"conversion":{"from":"USD","to":"EUR","amount":100,"result":92.00,"rate":0.92}}

```

--------------------------------

### Convert Currency

Source: https://github.com/wesbos/currency-conversion-mcp/blob/main/README.md

Converts a specified amount from one currency to another. It requires the source currency, target currency, and the amount to be converted.

```APIDOC
## POST /mcp

### Description
Converts a specified amount from one currency to another.

### Method
POST

### Endpoint
https://currency-mcp.wesbos.com/mcp

### Parameters
#### Request Body
- **from** (string) - Required - Source currency code (3 letters, e.g., "USD", "EUR")
- **to** (string) - Required - Target currency code (3 letters, e.g., "USD", "EUR")
- **amount** (number) - Required - Amount to convert (positive number)

### Request Example
```json
{
  "from": "USD",
  "to": "EUR",
  "amount": 100
}
```

### Response
#### Success Response (200)
- **converted_amount** (number) - The amount after conversion.
- **from** (string) - Source currency code.
- **to** (string) - Target currency code.

#### Response Example
```json
{
  "converted_amount": 92.50,
  "from": "USD",
  "to": "EUR"
}
```
```
Tokens:
Raw