tgju-rates-mcp
An MCP server and a small Python library that return the current Iranian free-market exchange rates in Rial (IRR) from tgju.org, as an array.
| Code | Currency | tgju page |
|---|---|---|
| USD | US Dollar | price_dollar_rl |
| EUR | Euro | price_eur |
| AED | UAE Dirham | price_aed |
| GBP | British Pound | price_gbp |
| TRY | Turkish Lira | price_try |
| CHF | Swiss Franc | price_chf |
| CNY | Chinese Yuan | price_cny |
| JPY | Japanese Yen (per 100 yen) | price_jpy |
| KRW | South Korean Won | price_krw |
| CAD | Canadian Dollar | price_cad |
| AUD | Australian Dollar | price_aud |
| NZD | New Zealand Dollar | 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
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:
claude mcp add tgju-rates -- uvx tgju-rates-mcp
Claude Desktop, Cursor and other clients (mcpServers config):
{
"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):
[
{
"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_rialis the price ofunitunits of the currency (unitis 100 for JPY, 1 for the rest). Divide by 10 for Toman.change_rialandchange_percentare magnitudes against the previous close;direction(up,down,flat) gives the sign.updated_atis 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
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
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 when a GitHub release tagged
v<version> is published. See CHANGELOG.md.
License
Metadata
Release files for tgju-rates-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tgju_rates_mcp-0.1.0.tar.gz | 11.6 kB | Without provenance | Details for tgju_rates_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tgju_rates_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for tgju_rates_mcp-0.1.0-py3-none-any.whl |
Total release size: 22.4 kB
Release files / tgju_rates_mcp-0.1.0.tar.gz
| Download URL | tgju_rates_mcp-0.1.0.tar.gz |
|---|---|
| Size | 11.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0df7d9d6da4bbd58cfcfb0b3c34eea6ff0664498a1b99c9d20d2e8c0e3b055f0
|
|
BLAKE2b-256 checksum How to use checksums |
70250239459ebe2501be124a78413e4648bebbf1af0577d4706895cb141c23c3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / tgju_rates_mcp-0.1.0-py3-none-any.whl
| Download URL | tgju_rates_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 10.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dd60f4d8320ab47148d7f70ce9da4e20cd6f75c81121583fdbde95947c0d974c
|
|
BLAKE2b-256 checksum How to use checksums |
c306884c2b208f302d61399bdc58e9aaad9b407f95a29d5e6f2a3a380ee9547c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for tgju-rates-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.