colombia-finance-mcp

An MCP server for Colombian financial data: gives Claude (or any MCP client) live access to the TRM — Colombia's official USD/COP exchange rate, certified by the Superintendencia Financiera — straight from the government open-data API. No API keys, no scraping.

Ask things like:

"What's today's TRM?" "How did the peso move in the first half of 2026? Min, max, average?" "How much is USD 2,500 in pesos at the official rate of last Friday?"

Tools

Example response from get_trm:

{
  "requestedDate": "2026-09-26",
  "copPerUsd": 3306.86,
  "validFrom": "2026-09-26",
  "validTo": "2026-09-28",
  "carriedOver": false,
  "source": "Source: TRM certified by the Superintendencia Financiera de Colombia, published on datos.gov.co (dataset 32sa-8pi3)."
}

Related MCP server: TCMB MCP

Quickstart

Requires Node.js ≥ 18.

git clone https://github.com/AlejandroGuerra1823/colombia-finance-mcp.git
cd colombia-finance-mcp
npm install && npm run build

Claude Code:

claude mcp add colombia-finance -- node /absolute/path/to/colombia-finance-mcp/dist/index.js

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "colombia-finance": {
      "command": "node",
      "args": ["/absolute/path/to/colombia-finance-mcp/dist/index.js"]
    }
  }
}

How it works

Claude ──(MCP / stdio)──▶ server.ts ──▶ trm.ts ──▶ datos.gov.co (Socrata API)
                          3 tools        │
                          zod-validated  ├─ validation (dates, series bounds)
                          inputs         ├─ in-memory cache (historical = immutable,
                                         │   current rate = 1h TTL)
                                         └─ stats engine (min/max/avg/Δ%)

Design decisions worth noting:

• TRM semantics are handled correctly. Each TRM record has a validity window; on weekends and holidays the last business-day rate carries over. Lookups resolve "latest record ≤ date", and responses flag carriedOver explicitly.

• Cache split by mutability. Historical rates never change → cached forever. The current rate can be superseded → 1-hour TTL.

• Errors are messages, not crashes. Invalid dates, empty ranges, oversized ranges and malformed upstream data all return structured MCP errors the model can read and act on.

• stdout is protocol-only. All logging goes to stderr, as the MCP stdio transport requires.

Development

npm run build   # compile TypeScript (strict mode)
npm test        # vitest — 16 unit tests (validation, stats, cache, error paths)

Roadmap

• UVR (Unidad de Valor Real) lookups

• IBR reference rate

• Colombian inflation (IPC) series

• npm package (npx colombia-finance-mcp)

Data source & disclaimer

Data comes from datos.gov.co dataset 32sa-8pi3, published by the Superintendencia Financiera de Colombia. This project is informational and not financial advice.

Author

Alejandro Guerra — AI Engineer · digital banking LinkedIn · Portfolio · GitHub

MIT © 2026