Skip to main content
Glama
tgju-rates-mcp

tgju-rates-mcp

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+.

Related MCP server: Arzbin MCP Server

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

Available Tools

1 tool
get_ratesIranian Rial exchange ratesA
Read-onlyIdempotent

Current free-market price in Iranian Rial of USD, EUR, AED, GBP, TRY, CHF, CNY, JPY (per 100), KRW, CAD, AUD and NZD, from tgju.org.

Args: currencies: ISO codes to return, in this order. Omit for all twelve.

Inputs: currencies. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides current exchange rates for various currencies via the Model Context Protocol, allowing AI models to fetch real-time currency data.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides live and historical foreign-exchange rates from the European Central Bank via Frankfurter API, enabling currency conversion, rate lookup, and trend analysis without API keys.
      5
      5 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides read-only access to Iranian market data from tgju.org, including live gold, coin, currency, and crypto prices, category tables, symbol search, and daily price history. Exposes six MCP tools for market summaries, live quotes, category browsing, and historical data with Jalali date filtering.
      6
      120 PyPI
      MIT