tgju-rates-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tgju-rates-mcp What's the current US dollar rate in Iranian rial?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | |
EUR | Euro | |
AED | UAE Dirham | |
GBP | British Pound | |
TRY | Turkish Lira | |
CHF | Swiss Franc | |
CNY | Chinese Yuan | |
JPY | Japanese Yen (per 100 yen) | |
KRW | South Korean Won | |
CAD | Canadian Dollar | |
AUD | Australian Dollar | |
NZD | New Zealand Dollar |
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-mcpor 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-mcpClaude Desktop, Cursor and other clients (mcpServers config):
{
"mcpServers": {
"tgju-rates": { "command": "uvx", "args": ["tgju-rates-mcp"] }
}
}Tool: get_rates
Argument | Type | Default |
| 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 |
|
| How long one tgju answer is reused. |
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-sourcesReleases are published to PyPI by GitHub Actions with
Trusted Publishing when a GitHub release tagged
v<version> is published. See CHANGELOG.md.
License
Available Tools
1 toolget_ratesIranian Rial exchange ratesARead-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
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.
Maintenance
Related MCP Connectors
Iranian rial/toman exchange rates (~30 currencies), conversion, history and gold. Free tier, no key.
Live Iran exchange rates, gold, crypto, and Toman market data for AI agents.
Live FX + official central-bank rates, 110+ sources. Hosted, keyless, nothing to install.
Free, source-labeled FX rates: 10,296 pairs across 144 currencies, all update ~60s intraday.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides current exchange rates for various currencies via the Model Context Protocol, allowing AI models to fetch real-time currency data.MIT

Arzbin MCP Serverofficial
AlicenseNot gradedqualityDmaintenanceLive Iran exchange rates, gold, crypto, and Toman/Rial market data for AI agents.2MIT- AlicenseAqualityBmaintenanceProvides 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.55 npmMIT
- AlicenseAqualityBmaintenanceProvides 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.6120 PyPIMIT