Skip to main content

tgju-rates-mcp

PyPI CI

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

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

MIT

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)

Source distribution for tgju-rates-mcp 0.1.0
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)

Table of built distributions (wheels) for tgju-rates-mcp 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page