tgju-rates-mcp
# tgju-rates-mcp
[](https://pypi.org/project/tgju-rates-mcp/)
[](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
Scored across 1 tool
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.
Single tool follows a clean verb_noun convention (get_rates) that matches its action exactly.
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.
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.