FX Currency

Provides real-time and historical FX data from Frankfurter API with GitHub OAuth authentication via an MCP server.

typescript

GitHub Stars

typescript

Language

6 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "pavm035-ai-fx-currency-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "fx_mcp_server.py",
        "--stdio"
      ],
      "env": {
        "AUTH_BASE_URL": "http://localhost:8080",
        "GITHUB_CLIENT_ID": "your_github_client_id",
        "GITHUB_CLIENT_SECRET": "your_github_client_secret"
      }
    }
  }
}

You can access real-time and historical foreign exchange data through a Python-based MCP server built on FastMCP. It supports 31+ currencies, on-demand conversions, current rates, historical data, and time series, all behind GitHub OAuth authentication for secure access. This guide shows you how to install, run, and use the FX Currency MCP Server with an MCP client.

How to use

Connect to the FX Currency MCP Server from your MCP client to retrieve current rates, perform conversions, and query historical and time series data. You’ll authenticate with GitHub, then request data through the MCP endpoints exposed by the server. The server runs as a local or development service and can be started in stdio mode so that your client spawns and communicates with the process directly.

Start the server in stdio mode using the runtime wrapper and the server script. This allows your MCP client to launch and communicate with the server directly. When running in stdio mode, you provide the runtime command and arguments so the client can spawn the server with the correct configuration.

How to install

Prerequisites you need before installation:

Python 3.13 or newer and a Python package installer. You will use the uv runtime (uvx) to run the server, or pip to install dependencies.

Concrete steps to get up and running from scratch:

# 1. Clone the project repository
git clone https://github.com/yourusername/ai-fx-mcp.git
cd ai-fx-mcp

# 2. Install dependencies via uv (preferred) or via pip
uv sync
# or
pip install -e .

# 3. Create and configure environment variables
cp .env.example .env

Configuration and security

Configure GitHub OAuth credentials to enable secure login. You will add the OAuth client ID and client secret, along with the base URL for authentication, to your environment file.

GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
AUTH_BASE_URL=http://localhost:8080

Running the server

To run in stdio mode (recommended for MCP clients that spawn the server), use the runtime command shown in the example configuration. This starts the FX Currency MCP Server so your MCP client can communicate with it.

uv run python fx_mcp_server.py --stdio

Starting with MCP clients

Your MCP client will spawn the server process in stdio mode and connect through the standard input/output streams. Ensure the client passes the same command and arguments used above so the server starts in the correct mode and location.

Available tools

available_currencies

Returns a list of all supported currency codes and names.

convert_currency

Converts a given amount from one currency to another using current rates.

today_rates

Fetches current exchange rates using a specified base currency.

historical_rates

Retrieves exchange rates for a specific historical date with optional base and symbols.

time_series_rates

Gets exchange rate data over a date range with optional base and symbols.

Built by

VeilStrat

AI signals for GTM teams