# colombia-finance-mcp

[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-3fd6c2)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org/)
[![Tests](https://img.shields.io/badge/tests-16%20passing-brightgreen)](#development)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

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

| Tool | What it does |
|---|---|
| `get_trm` | Official TRM (COP per USD) for any date since 1991 — today by default. Correctly resolves weekends/holidays to the carried-over rate. |
| `get_trm_range` | Daily TRM series between two dates (up to ~5 years) with statistics: min, max, average, percent change. Long ranges are auto-sampled. |
| `convert_usd_cop` | Converts USD ⇄ COP at the official TRM of any date. |

Example response from `get_trm`:

```json
{
  "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)."
}
```

## Quickstart

Requires Node.js ≥ 18.

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

**Claude Code:**

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

**Claude Desktop** (`claude_desktop_config.json`):

```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

```bash
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](https://www.datos.gov.co/Econom-a-y-Finanzas/Tasa-de-Cambio-Representativa-del-Mercado-TRM/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](https://linkedin.com/in/alejandro-guerra-developer) · [Portfolio](https://alejo-guerra-dev.vercel.app) · [GitHub](https://github.com/AlejandroGuerra1823)

MIT © 2026