Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-trm-colombia Convert 500 USD to COP at today's official rate."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The problem: ask any LLM what a dollar is worth in Colombian pesos and it will confidently make one up — a number from its training data, months stale, with no source.
What this does: gives the model the official rate. An MCP server over Colombia's TRM (Tasa Representativa del Mercado), published by the Superintendencia Financiera as open data. Every answer carries the exact rate used and the dates it is valid for, so it can be audited.
Try it:
uvx --from git+https://github.com/andresFLZ/mcp-trm-colombia mcp-trm-colombiahttps://github.com/user-attachments/assets/a2e5ba43-9727-4638-a4df-f68cbd58c455
Because the awkward parts are not the HTTP request. They are the rules a model gets wrong on its own:
One rate covers several days. The rate published on a Friday is normally valid through Sunday, and holidays stretch it further. Asking "the rate on Saturday" and getting nothing back is a bug; this returns the rate in force, with its window.
"Today" is ambiguous. Colombia is UTC-5 with no DST. A model reasoning in UTC asks for tomorrow and gets "not published yet". Handled here, once.
Old rates never change; today's still can. History is cached forever, the current one never is.
Every number needs provenance. A conversion that does not say which rate it used cannot be checked by anyone.
Related MCP server: Economía Venezuela MCP
Tool | What it answers |
| The official rate in force on a date, with its validity window |
| USD ⇄ COP at the rate for that date, reporting the rate used |
| Every rate in a period, plus min, max, average and the change across it |
| Today's date in Colombia and today's rate |
All dates are ISO YYYY-MM-DD. date defaults to today in Bogotá.
A tool that throws leaves the model guessing. Every failure comes back as data, including the one field it actually needs — whether trying again could help:
{
"ok": false,
"error": "source_unavailable",
"message": "datos.gov.co did not respond in time. It is an open-data portal and it is occasionally slow; retrying usually works.",
"retryable": true
}
| Means |
|
| Bad date, unknown currency, negative amount |
|
| Valid date, no rate published for it |
|
| datos.gov.co timed out, errored, or sent something unreadable |
|
Requires Python 3.10+ and the MCP Python SDK 2.x.
git clone https://github.com/andresFLZ/mcp-trm-colombia
cd mcp-trm-colombia
pip install -e ".[dev]"This repo ships a .mcp.json, so a client opened in this directory finds the
server with no configuration at all. For Claude Desktop, add this to
claude_desktop_config.json and restart it:
{
"mcpServers": {
"trm-colombia": {
"command": "uvx",
"args": ["--from", "git+https://github.com/andresFLZ/mcp-trm-colombia", "mcp-trm-colombia"]
}
}
}{
"mcpServers": {
"trm-colombia": {
"command": "python",
"args": ["-m", "mcp_trm_colombia.server"],
"env": { "PYTHONPATH": "/absolute/path/to/mcp-trm-colombia/src" }
}
}
}Then ask, in plain language:
"I invoiced USD 1,850 on August 15th. How many pesos was that at the official rate?" "How much did the peso move against the dollar this month?"
datos.gov.co dataset 32sa-8pi3 —
Tasa de Cambio Representativa del Mercado Histórico, published by the
Superintendencia Financiera de Colombia. Public, no API key, series starts
1991-12-02.
31 tests. 28 run offline against a mock transport, so the suite is deterministic and does not depend on a government portal being up:
pytest # 28 offline tests
pytest -m live # 3 more, against the real datasetThe offline set deliberately covers the failure paths, not just the happy one: HTTP 503, timeouts, malformed bodies, rows with missing fields, dates before the series begins, dates too far ahead, reversed ranges, negative amounts, unknown currencies — and that history is cached while today's rate is not.
trm.py has no MCP import. The domain logic is plain Python and is tested
on its own; server.py only adapts it. Swapping the transport touches one file.
Decimal, never float, for money. Rounding happens once, at the edge.
The cache follows the data. A settled past rate is immutable, so it is kept forever. Today's can still be superseded, so it is re-read every time.
Errors are a taxonomy, not one catch-all. "You asked for something impossible" and "the source is down" need different reactions from the caller.
Built against MCP SDK 2.x (MCPServer). The 1.x name for the same class
was FastMCP.
MIT — see LICENSE.
Convert an amount between USD and COP at the official rate.
Args:
amount: How much to convert. Must be zero or positive.
currency: The currency of amount — "USD" or "COP".
date: ISO date of the rate to use. Defaults to today in Bogota.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| amount | Yes | ||
| currency | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the burden. It adds useful behavioral context: amount must be zero or positive, currency restricted to USD/COP, default date is today in Bogota, and it uses the official rate. However, it does not disclose edge-case behavior (invalid currency, historical rate availability) or explicitly state that it is a read-only calculation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the action, and structured as an Args block that is easy to scan. Every sentence adds information; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple conversion tool with an output schema, the description covers purpose and all parameters. Minor gaps remain around usage differentiation and edge cases, but the core call semantics are complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description fully compensates by documenting all three parameters: amount (constraint), currency (allowed values), date (format, default, timezone). This goes well beyond the bare type declarations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Convert') plus resource (amount between USD and COP) and the rate basis ('official rate'). It is clearly differentiated from sibling tools like get_trm/trm_series/today, which retrieve rate data or the current date rather than performing conversions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to choose convert versus siblings. The description implies its use case through the verb, but it does not mention alternatives, exclusions, or prerequisites. For example, it does not clarify that get_trm would be used to fetch the raw rate instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Official USD/COP rate in force on a date.
Args: date: ISO date (YYYY-MM-DD). Defaults to today in Bogota.
A single rate often covers several days — the one published on Friday usually runs through Sunday — so the answer includes its validity window.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It usefully reveals that one rate often covers multiple days and that the answer includes its validity window, which is non-obvious behavioral context. It does not discuss error cases, but the basic query behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and front-loaded: a one-sentence purpose, a brief Args block, and one essential behavioral note. Every sentence adds information; nothing is redundant or padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-optional-parameter lookup tool with an output schema, this is complete. It explains the input format, default behavior, timezone, and the non-obvious validity-window aspect of the result. No critical guidance is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only shows an optional string/null date with a null default, but the description adds the ISO format (YYYY-MM-DD) and clarifies that the default is 'today in Bogota.' This fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: it returns the 'Official USD/COP rate in force on a date.' This clearly identifies the tool's sole job and distinguishes it from siblings like trm_series (a series of rates) and convert (currency conversion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended use obvious: retrieve the official rate for a specific date, defaulting to today in Bogota. It does not explicitly name alternatives or state when not to use this tool, so it stops just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Today's date in Colombia (UTC-5), and today's rate.
Exists because models routinely get "today" wrong, and every other tool here defaults to it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It usefully discloses the timezone (UTC-5) and that the value is intentionally pinned to 'today.' But it does not explain what happens on non-business days, which rate is returned, or other edge-case behavior, leaving some important behavior implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded, and free of filler. The first sentence states what the tool returns and the second justifies its existence; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-argument utility with an output schema available, the description is nearly complete: it provides the location/timezone, the value returned, and the reason to use it. It could more explicitly state the rate type or non-trading-day handling, but those are minor given the sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so parameter documentation is not needed and baseline 4 applies. Nothing about parameter meaning is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies what the tool provides: today's date in Colombia (UTC-5) and today's rate. It also hints at differentiation by noting that other tools default to 'today.' However, it lacks a direct action verb and never names the rate type explicitly, so it is clear but not maximally precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The rationale explains why this tool exists: models often get 'today' wrong, and other tools default to it. This gives an agent clear context for when to call it instead of reasoning about the current date. It does not explicitly list exclusions or alternatives, but the sibling names and the default-today note provide enough guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rates over a period, with min, max, average and the change across it.
Args: start_date: ISO date (YYYY-MM-DD), inclusive. end_date: ISO date (YYYY-MM-DD), inclusive. Max 5 years apart.
Returns the summary plus the raw series, so the caller can chart it without a second round trip.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | ||
| start_date | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses important behavior: inclusive dates, a 5-year maximum span, and that both summary and raw series are returned. It does not mention operational caveats such as output ordering, error cases, or whether the operation is strictly read-only, though that is strongly implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with an Args section and a Returns note. Every sentence contributes meaningful information without redundancy or unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description is complete: it explains the date range semantics, max span, and return structure. The mention of charting without a second round trip gives useful purpose context without requiring additional detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It fully documents both parameters with ISO format, inclusivity, and the 5-year constraint, adding substantial meaning beyond the bare schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states that the tool returns rates over a period with min, max, average, and change, which clearly identifies the resource and output. It does not explicitly contrast itself with sibling tools like get_trm, so it lacks full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it is for rates over a date range and returns the raw series so callers can chart without a second request. It does not explicitly mention alternatives or when not to use this tool, but the context is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0convertget_trmtodaytrm_seriesScored across 4 tools
Most tools are clearly distinct: get_trm fetches a single rate, convert performs currency conversion, and trm_series returns period statistics. There is mild overlap between get_trm and today, since both can supply today's rate, but the descriptions clarify that today is a convenience wrapper for date anchoring.
The names are readable and lowercase, but they do not follow a single pattern: get_trm uses verb_noun, convert is a bare verb, trm_series is a noun phrase, and today is a standalone time reference. This mixed style is understandable but not fully consistent.
Four tools is well-scoped for a specialized TRM server. Each tool addresses a distinct need: single rate lookup, conversion, historical series analysis, and current date context, with no redundant bulk.
The server covers the core domain completely: fetching current or historical rates, converting between USD and COP, and obtaining series summaries with statistics. The inclusion of today's date fills a practical gap, and there are no obvious missing operations for this narrow purpose.
Live & historical FX rates and currency conversion for AI agents. No API keys.
Live & historical FX rates and currency conversion for AI agents. No API keys.
Loan & mortgage calculator, compound interest, ROI, crypto prices, FX conversion for AI agents.
60+ units, live FX, timezones, and date arithmetic for AI agents.