Skip to main content
Glama
latamfx-mcp

latamfx-mcp

by floreskemec

latamfx-mcp

An MCP server that exposes public LatAm FX data and an auditable reconciliation engine to AI agents (Claude Desktop, Claude Code, or any MCP client).

CI Python MCP Ruff Checked with mypy License: MIT

latamfx-mcp lets an LLM agent answer questions like "what's the blue dollar today?", "convert 1,500 USD to ARS at the MEP rate", or "reconcile these two ledgers and tell me what didn't match" — entirely from free, key-less public APIs. No credentials, no client data.

It doubles as a reference implementation of a production-shaped MCP server: hexagonal architecture, typed contracts, retries with backoff, a TTL cache, contract tests against mocked HTTP, CI, Docker and a Cloud Run deployment module.


Tools

Tool

What it does

list_fx_sources

List supported sources (oficial, blue, MEP, CCL, mayorista, cripto, tarjeta).

get_fx_quote

Latest buy/sell quote for a source.

get_fx_timeseries

Historical buy/sell series (most recent N points).

get_fx_stats

min / max / mean / volatility of the mid price (computed with Polars).

convert

Convert an amount between currencies using a source's quote (USD↔ARS).

reconcile

Match two ledgers with a multi-rule engine; returns matches, misses and a match rate.

Plus a resource: fx://sources (the source catalog as text).

The reconciliation engine

reconcile is a sanitized, generic version of intercompany / bank reconciliation engines used in real fintech work. Rules run in priority order and each right-side entry is consumed at most once, so the output is a valid one-to-one assignment where every match is traceable to the rule that produced it:

  1. exact_reference — same non-empty external reference (score 1.0).

  2. amount_date — equal amount within a day-tolerance window (score decays with the gap).

  3. fuzzy_description — equal amount + similar free-text description above a threshold.


Related MCP server: veradata

Architecture

Hexagonal (ports & adapters): the domain and application layers know nothing about HTTP or MCP, so the engine is pure and the data source is swappable.

flowchart TD
    Agent[AI agent / MCP client] -->|tools, resources| Server[server.py · FastMCP]
    Server --> App[application · FxService, ReconciliationService]
    App --> Domain[domain · models + reconciliation engine]
    App -->|FxProvider port| Port{{ports}}
    Port -.implemented by.-> Adapter[infrastructure · DolarApiProvider]
    Adapter -->|httpx + retries + TTL cache| Public[(dolarapi.com / argentinadatos.com)]
src/latamfx_mcp/
├── domain/           # pure models + reconciliation engine (no I/O)
├── ports/            # FxProvider Protocol (dependency inversion)
├── application/      # use cases: FX + reconciliation
├── infrastructure/   # httpx adapter, retry policy, TTL cache
├── config.py         # env-driven settings
└── server.py         # FastMCP wiring (tools + resource)

See docs/architecture.md and the ADRs for the design decisions.


Quickstart

Requires uv.

git clone https://github.com/floreskemec/latamfx-mcp.git
cd latamfx-mcp
uv sync
uv run latamfx-mcp     # starts the MCP server over stdio

Use it from Claude Code

claude mcp add latamfx -- uv --directory /absolute/path/to/latamfx-mcp run latamfx-mcp

Use it from Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "latamfx": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/latamfx-mcp", "run", "latamfx-mcp"]
    }
  }
}

Then ask Claude: "Using latamfx, convert 1500 USD to ARS at the blue rate and show me the last 7 days of the blue dollar."


Development

uv sync
uv run pytest            # tests + coverage
uv run ruff check .      # lint
uv run ruff format .     # format
uv run mypy              # static types

Configuration is read from environment variables (all optional):

Variable

Default

Purpose

LATAMFX_HTTP_TIMEOUT

10.0

HTTP timeout (seconds).

LATAMFX_HTTP_RETRIES

3

Max attempts on transient failures.

LATAMFX_CACHE_TTL

60.0

Quote/series cache TTL (seconds).


Deployment

A multi-stage Dockerfile builds a slim image, and deploy/terraform contains a minimal OpenTofu/Terraform module to run it on Google Cloud Run. See the deploy README.


Data sources

Both are free, community-maintained public APIs. This project is not affiliated with them; please review their terms before heavy use.

License

MIT © Gonzalo Flores Kemec

Available Tools

6 tools
convertB

Convert an amount between currencies using a source's quote (e.g. USD<->ARS).

Inputs: amount (required), from_currency (required), to_currency (required), source. Returns: object

get_fx_quoteA

Get the latest buy/sell quote for an FX source (e.g. 'blue', 'oficial').

Inputs: source (required). Returns: object

get_fx_statsB

Summary statistics (min/max/mean/volatility) of a source's mid price.

Inputs: source (required). Returns: object

get_fx_timeseriesB

Get the historical buy/sell series for a source (most recent last_n).

Inputs: source (required), last_n. Returns: object

list_fx_sourcesA

List the supported FX sources (Argentine dollar variants).

Inputs: no named parameters. Returns: result

reconcileA

Reconcile two ledgers with a multi-rule engine (exact ref, amount+date, fuzzy).

Returns matched pairs (with the rule and a confidence score), unmatched ids on each side, and the overall match rate.

Inputs: left (required), right (required), day_tolerance, fuzzy_threshold, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have distinct purposes (conversion, quotes, stats, timeseries, source listing). However, 'reconcile' introduces a separate domain (ledger reconciliation) which could be confusing but does not overlap with FX tools.

    Naming Consistency3/5

    Naming conventions are mixed: 'convert' and 'reconcile' are bare verbs, while others use 'get_fx_*' or 'list_fx_*' pattern. This inconsistency could be confusing.

    Tool Count4/5

    6 tools is a reasonable number for an FX-focused server plus a reconciliation tool. It feels slightly heavy but still manageable.

    Completeness4/5

    Core FX operations (list sources, get quote, timeseries, stats, convert) are covered. The inclusion of reconciliation is a bonus but not part of the expected surface, so minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      B
      maintenance
      MCP server providing verified Latin American data via x402 micropayments. 4 MCP tools: vera_rates (central bank rates CO/MX/BR/CL/PE), vera_sanctions (OFAC+SARLAFT+CNBV+COAF+UAF screening, EU AI Act Art.13), vera_entity (RUES/CNPJ/RFC enrichment), vera_context (AI market intelligence). $0.02–$0.10 USDC per call.
      4
      -
    • F
      license
      A
      quality
      D
      maintenance
      Verified Latin American data for autonomous AI agents via x402 micropayments. Sanctions screening (OFAC SDN + SARLAFT + CNBV + COAF + UAF) with EU AI Act Art.12/13 compliant hash-chain audit trail, entity enrichment (RUES/CNPJ/RFC), and real-time LATAM central bank rates including Argentina dólar blue. $0.02–$0.10 USDC per call on Base and Solana. No API key required.
      4
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables LLMs to retrieve the official Colombian TRM (USD/COP exchange rate) with its validity window, perform currency conversions, and analyze rate series, all with auditable provenance.
      4
      MIT