tgju-mcp: TGJU MCP server for AI agents (dollar, gold, coin and crypto prices in Iran)

Let your AI agent read live Iranian market prices from TGJU (tgju.org).
An unofficial, read-only MCP server for TGJU (شبکه اطلاع‌رسانی طلا، سکه و ارز), Iran's market-price portal:
dollar, euro, gold, coin, crypto and commodity prices, category tables and daily history, from Claude, Cursor or Copilot.

For AI agents · Why · What it can do · Quick start · Tools · How it works · Good to know · FAQ · Configuration · فارسی · Development

For AI agents

• What: unofficial MCP server (model context protocol) for tgju.org, the Iranian portal for dollar, gold, coin, crypto and commodity prices. Symbol search takes Persian and English names.
• Install: uvx tgju-mcp or claude mcp add tgju -- uvx tgju-mcp. Transport: stdio. Needs uv (Python 3.10+).
• Auth: none, no API key or account. Optional TGJU_MCP_PROXY (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
• Access: read-only. It cannot log in or trade, so no confirmation is needed before calling any tool.
• Tools: 6, all prefixed tj_. Typical sequence: tj_market_summary -> tj_category_table -> tj_price_history. If you only have a name, call tj_search_symbols first and pass its symbol to the other tools.
• Use when: the user asks for the dollar, euro, gold, coin, Bitcoin or Brent price in Iran, a price table of a group, or a symbol's daily history.
• Do not use when: the user wants to trade or buy anything, needs stock-exchange (TSETMC) data, or asks about markets outside the TGJU feed.
• Output: compact JSON. Iranian prices are quoted by the site in Rial; those symbols also carry *_toman (Rial / 10). Global symbols (ounce, Brent, crypto in USD, currency pairs) keep their listed unit (unit: as_listed).
• Machine-readable: server.json and the awesome-iran-mcp catalog.

Why

TGJU is where Iranians check the dollar, gold and coin price, but it is a busy web page with hundreds of symbols. Asking "what is the dollar, the 18k gold gram and the Emami coin right now, and how did the dollar move over the last month?" means several screens. With tgju-mcp an agent answers it in a few calls and returns a short summary instead of raw tables.

You: What are the main rates today, and how has the dollar moved recently?

Agent: calls tj_market_summary -> tj_search_symbols -> tj_price_history

It reads the key rates in one call, finds the dollar symbol, and summarises its recent daily closes.

Every reply is trimmed to stay under about 15 KB, so it does not flood the agent's context.

What it can do

• Summarise the market in one call: dollar, euro, dirham, pound, lira, gold gram and ounce, coins, silver, Brent, Bitcoin, Ethereum, Tether
• Quote symbols: live price, change, high and low for one or more symbols
• List price tables of a group: gold, coin, retail coin, currency, government currency, Sana, Nima, crypto, or any folder id
• Browse the market tree to find folders and symbols
• Search symbols by name across internal, global and crypto markets
• Pull daily history: open, low, high, close and change, with Jalali date filters
• Read-only by design: no login, no trading

Example prompts:

• "What is the dollar, euro and 18k gold gram price right now?"
• "Show the coin price table."
• "How has the free-market dollar moved over the last 30 days?"
• "Price of Bitcoin and Tether in Toman."
• "Find the symbol for Brent oil and show its latest price."
• قیمت دلار، یورو و طلای ۱۸ عیار الان چند است؟
• جدول قیمت سکه امروز را نشان بده.
• روند قیمت دلار در یک ماه گذشته چطور بوده؟

Quick start

You need uv. No API key or account.

claude mcp add tgju -- uvx tgju-mcp

{
  "mcpServers": {
    "tgju": { "command": "uvx", "args": ["tgju-mcp"] }
  }
}

{
  "servers": {
    "tgju": { "type": "stdio", "command": "uvx", "args": ["tgju-mcp"] }
  }
}

codex mcp add tgju -- uvx tgju-mcp

[mcp_servers.tgju]
command = "uvx"
args = ["tgju-mcp"]

{
  "mcpServers": {
    "tgju": { "command": "uvx", "args": ["tgju-mcp"] }
  }
}

Tools

Symbols are lower-case slugs such as price_dollar_rl, geram18 or sekee. If you do not know one, call tj_search_symbols first.

All 6 tools are annotated readOnlyHint: true.

How it works

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  tgju-mcp  (runs on your machine)
      │
      │  HTTPS
      └──────▶  api.tgju.org, call4.tgju.org   live feed, tables, history, search

tgju-mcp runs locally and calls the same endpoints the tgju.org site uses. It has no hosted server in between and no API key. Requests go out through a Chrome-impersonating client, at most 2 at a time with a little jitter. Answers are kept for 15 seconds, a failed GET is retried, and it only talks to api.tgju.org and call4.tgju.org. It only reads.

Good to know

• Units: the feed has no unit field. Gold grams, coins, free-market and other price_* currencies and crypto-*-irr are in Rial (*_toman = Rial / 10). ons, silver, oil_*, crypto-* (USD) and pairs like usd-try-ask keep their listed unit (as_listed).
• Unit rule is a heuristic on the symbol name, so check unusual symbols against tgju.org. Folder-id tables apply it per row (unit: mixed); symbols outside it, such as exchange-house quotes with slug names, stay as_listed.
• Reply caps: tj_category_table and tj_price_history return at most 50 rows, so replies stay under about 14 KB.
• Stale quotes: a quote older than 2 days carries stale: true. Illiquid symbols can be delayed, so check time.
• Symbols missing from the live feed (slugs from tj_search_symbols) are answered by tj_get_prices with the latest daily close (source: history, time = date).
• Dates: history returns Gregorian and Jalali dates; from_date and to_date filters are Jalali YYYY/MM/DD.
• Search returns at most 10 hits.
• What it does not do: no trading or orders, no account features, no prices outside the TGJU feed.
• Network: tgju.org answered plain requests from both a proxy and a direct connection when tested. If your network blocks it, set TGJU_MCP_PROXY. System proxy variables are ignored on purpose.

FAQ

npx @modelcontextprotocol/inspector uvx tgju-mcp

Configuration

فارسی: سرور MCP قیمت دلار، طلا و سکه (TGJU)

claude mcp add tgju -- uvx tgju-mcp

Development

git clone https://github.com/sepehr071/tgju-mcp && cd tgju-mcp
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q          # offline unit tests
uv run python -m pytest -m live -q  # calls tgju.org
uv build

All tools live in src/tgju_mcp/markets.py; each is a typed async function with a docstring that tells the agent when to use it. Issues and PRs are welcome.

Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions publishes to PyPI.

Related servers

• awesome-iran-mcp: catalog of all Iranian-service MCP servers
• tsetmc-mcp for Tehran Stock Exchange quotes and indices
• iran-crypto-mcp for crypto prices on Iranian exchanges
• milligold-mcp for gold prices on Milli
• iran-news-mcp for Iranian news

Disclaimer

Unofficial and not affiliated with or endorsed by TGJU. It is read-only and uses the endpoints of the tgju.org web app, which can change without notice. Prices are informational, may be delayed, and are not financial advice.

License

MIT