Skip to main content
Glama
tgju-rates-mcp

tgju-rates-mcp

README.md
# tgju-rates-mcp

[![PyPI](https://img.shields.io/pypi/v/tgju-rates-mcp)](https://pypi.org/project/tgju-rates-mcp/)
[![CI](https://github.com/SaeedNoshadi89/tgju-rates-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SaeedNoshadi89/tgju-rates-mcp/actions/workflows/ci.yml)

An [MCP](https://modelcontextprotocol.io) server and a small Python library that return the
current Iranian **free-market** exchange rates in **Rial (IRR)** from
[tgju.org](https://www.tgju.org/currency), as an array.

| Code | Currency | tgju page |
| --- | --- | --- |
| USD | US Dollar | [price_dollar_rl](https://www.tgju.org/profile/price_dollar_rl) |
| EUR | Euro | [price_eur](https://www.tgju.org/profile/price_eur) |
| AED | UAE Dirham | [price_aed](https://www.tgju.org/profile/price_aed) |
| GBP | British Pound | [price_gbp](https://www.tgju.org/profile/price_gbp) |
| TRY | Turkish Lira | [price_try](https://www.tgju.org/profile/price_try) |
| CHF | Swiss Franc | [price_chf](https://www.tgju.org/profile/price_chf) |
| CNY | Chinese Yuan | [price_cny](https://www.tgju.org/profile/price_cny) |
| JPY | Japanese Yen (**per 100 yen**) | [price_jpy](https://www.tgju.org/profile/price_jpy) |
| KRW | South Korean Won | [price_krw](https://www.tgju.org/profile/price_krw) |
| CAD | Canadian Dollar | [price_cad](https://www.tgju.org/profile/price_cad) |
| AUD | Australian Dollar | [price_aud](https://www.tgju.org/profile/price_aud) |
| NZD | New Zealand Dollar | [price_nzd](https://www.tgju.org/profile/price_nzd) |

> Not affiliated with tgju.org. Rates are tgju's unofficial market quotes, not Central Bank of
> Iran rates. Respect tgju's terms of use; by default the built-in cache reuses one successful answer for
> 60 seconds per process.

## Install

```sh
uv add tgju-rates-mcp
```

or `pip install tgju-rates-mcp`. Requires Python 3.10+.

## Use as an MCP server

The package installs a `tgju-rates-mcp` command that serves MCP over stdio. Without installing
anything, `uvx tgju-rates-mcp` runs it.

Claude Code:

```sh
claude mcp add tgju-rates -- uvx tgju-rates-mcp
```

Claude Desktop, Cursor and other clients (`mcpServers` config):

```json
{
  "mcpServers": {
    "tgju-rates": { "command": "uvx", "args": ["tgju-rates-mcp"] }
  }
}
```

### Tool: `get_rates`

| Argument | Type | Default |
| --- | --- | --- |
| `currencies` | array of the codes above | all twelve, in the table's order |

It returns an array (as MCP structured content under `result`):

```json
[
  {
    "code": "USD",
    "name": "US Dollar",
    "price_rial": 2659000,
    "unit": 1,
    "change_rial": 40000,
    "change_percent": 1.5,
    "direction": "down",
    "high_rial": 2691100,
    "low_rial": 2659000,
    "updated_at": "2026-11-15T13:44:56+03:30",
    "source_url": "https://www.tgju.org/profile/price_dollar_rl"
  }
]
```

- `price_rial` is the price of `unit` units of the currency (`unit` is 100 for JPY, 1 for the
  rest). Divide by 10 for Toman.
- `change_rial` and `change_percent` are magnitudes against the previous close; `direction`
  (`up`, `down`, `flat`) gives the sign.
- `updated_at` is tgju's own update time, in Tehran time (UTC+03:30).

If tgju cannot be reached, or any requested currency is missing or malformed in its answer, the
tool returns an error instead of a partial or guessed list.

### Configuration

| Environment variable | Default | Meaning |
| --- | --- | --- |
| `TGJU_RATES_CACHE_SECONDS` | `60` | How long one tgju answer is reused. `0` turns caching off. |

## Use as a library

```python
import asyncio
from tgju_rates_mcp import TgjuRatesClient

client = TgjuRatesClient()  # keep one per process; it holds the cache


async def main() -> None:
    for rate in await client.get_rates(["USD", "EUR"]):
        print(rate.code, rate.price_rial)


asyncio.run(main())
```

`get_rates()` returns a list of `Rate` (pydantic) objects and raises `TgjuError` when tgju's
answer is unusable, or `ValueError` for an unsupported code. Options:
`TgjuRatesClient(cache_seconds=60, timeout_seconds=10, http_client=None)`; pass your own
`httpx.AsyncClient` to share connection pools or proxies.

## How it works

tgju's pages load their numbers from one JSON feed (`https://call1.tgju.org/ajax.json`). The
package reads that feed (at most 5 MB, and at most 10 s for the whole request), takes the twelve entries above and keeps a
value only if it parses strictly as a number; English names come from the package itself, never
from the site. Persian digits and separators are normalised. A feed that cannot answer is not
cached. Every field the result needs must be present: missing values are never defaulted. The feed is not a documented API: if tgju changes it, the tool fails loudly and a new
release is needed.

## Development

```sh
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv build --no-sources
```

Releases are published to PyPI by GitHub Actions with
[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) when a GitHub release tagged
`v<version>` is published. See [CHANGELOG.md](CHANGELOG.md).

## License

[MIT](LICENSE)

TDQS

A4.2/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of misselection or overlap. Its purpose (return current Iranian Rial free-market rates for a list of currencies) is explicit and self-contained.

Naming Consistency5/5

Single tool follows a clean verb_noun convention (get_rates) that matches its action exactly.

Tool Count4/5

One tool is proportionate for a narrowly scoped rate-lookup service, though it leaves the surface thin with no alternative access patterns. It is well-scoped rather than mismatched, but sits below the typical 3-15 comfort band.

Completeness4/5

Coverage of the twelve currencies with an optional filter is complete for a snapshot price lookup. Minor gaps exist only for adjacent things tgju publishes (historical series, gold/coin rates) that fall outside the stated purpose.

Maintenance

ActivityNo data
ResponsivenessOutdated data