Skip to main content
Glama
tgju-mcp

tgju-mcp

by sepehr071

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.

PyPI Python CI MCP Registry License: MIT mcpfarsi

Install in VS Code

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 iran-mcp catalog.

Related MCP server: ime-mcp

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

Settings → Developer → Edit Config, then add:

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

Add the Claude Desktop block above to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

Click Install in VS Code above, or add to .vscode/mcp.json:

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

Or in ~/.codex/config.toml:

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

Add to ~/.gemini/settings.json:

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

Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.

It is a standard stdio MCP server: run uvx tgju-mcp, or pip install tgju-mcp and run 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.

Tool

What it does

tj_market_summary

Key Iranian market rates in one call: dollar, euro, dirham, pound, lira, gold gram and ounce, coins, silver, Brent, Bitcoin, Ethereum, Tether

tj_get_prices

Live price, day change, high and low for one or more TGJU symbols

tj_category_table

Live price table of one TGJU group: price, change, day high/low/open per symbol

tj_list_categories

Browse TGJU's market tree: folders (with ids) and symbols

tj_search_symbols

Find TGJU symbols by name

tj_price_history

Daily history (open, low, high, close, change) of a TGJU symbol, for charts and trend questions

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

TGJU has no documented public API. tgju-mcp is an unofficial MCP server with 6 read-only tools that calls the same endpoints the tgju.org web app uses and returns compact JSON for AI agents.

Add the server with claude mcp add tgju -- uvx tgju-mcp, or use the matching config in Quick start, then ask in plain language, in Persian or English.

TGJU quotes Iranian prices in Rial. Those symbols also come back as *_toman (Rial / 10). Global symbols such as the gold ounce, Brent and crypto in USD keep their listed unit.

Call tj_market_summary for the main rates, or tj_search_symbols with a name (Persian or English) and pass the returned symbol to tj_get_prices or tj_price_history.

Some symbols are illiquid or no longer updated. A quote older than 2 days is marked stale: true; check the time field.

No. It has no login and no trading calls, it only reads public prices. Nothing it returns is financial advice.

It is what TGJU serves, kept for up to 15 seconds in a local cache, and it may be delayed.

npx @modelcontextprotocol/inspector uvx tgju-mcp

Configuration

Variable

Default

Meaning

TGJU_MCP_PROXY

unset

Optional HTTP proxy URL for tgju.org requests; system proxy settings are ignored. Also accepts a comma-separated list: one is used until it gets blocked or fails to connect, then the next

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

tgju-mcp یک سرور MCP غیررسمی و فقط‌خواندنی برای سایت TGJU (شبکه اطلاع‌رسانی طلا، سکه و ارز) است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد قیمت دلار، یورو، طلا، سکه، ارز دیجیتال و کالاها را از tgju.org بخواند.

چه کارهایی می‌کند

  • خلاصه بازار در یک فراخوانی: دلار، یورو، درهم، پوند، لیر، گرم و اونس طلا، سکه‌ها، نقره، برنت، بیت‌کوین، اتریوم و تتر.

  • قیمت لحظه‌ای نماد با تغییر روز، بیشترین و کمترین قیمت.

  • جدول قیمت گروه‌ها: طلا، سکه، ارز، ارز دولتی، ارز نیما، ارز سنا، ارز دیجیتال.

  • جستجوی نماد و گشت‌وگذار در درخت بازار.

  • تاریخچه روزانه قیمت (باز، کم، زیاد، پایانی و تغییر) با فیلتر تاریخ شمسی، تا ۵۰ ردیف.

نکته‌ها

  • فقط خواندنی است: وارد حساب نمی‌شود و خرید و فروش انجام نمی‌دهد. توصیه مالی نیست.

  • قیمت‌های ایرانی در سایت به ریال است و برای آن‌ها فیلد تومان (ریال تقسیم بر ۱۰) هم برمی‌گردد. نمادهای جهانی (اونس، برنت، ارز دیجیتال به دلار) واحد خودشان را دارند.

  • قیمت نمادهای کم‌معامله ممکن است قدیمی باشد؛ فیلد time را ببینید.

  • کلید API لازم نیست و روی سیستم خود شما اجرا می‌شود. در صورت نیاز به پراکسی، متغیر TGJU_MCP_PROXY را بگذارید.

نصب (اول uv را نصب کنید). در Claude Code:

claude mcp add tgju -- uvx tgju-mcp

در Claude Desktop، Cursor و بقیه برنامه‌ها همان تنظیم بخش Quick start را بگذارید.

نمونه پرسش‌ها

  • «قیمت دلار و طلای ۱۸ عیار الان چند است؟»

  • «جدول قیمت سکه را نشان بده.»

  • «روند دلار آزاد در ۳۰ روز گذشته چطور بوده؟»

  • «قیمت بیت‌کوین و تتر به تومان چقدر است؟»

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.

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.

Author

Built and maintained by Sepehr Radmard (سپهر رادمرد). Connect on LinkedIn or follow @sepehr071 on GitHub for more MCP servers for Iranian websites, all listed in iran-mcp. If this saves you time, a star on the repo helps other people find it.

License

MIT

Available Tools

6 tools
tj_category_tableCategory price tableA
Read-onlyIdempotent

Live price table of one TGJU group: price, change, day high/low/open per symbol.

Use for 'all gold prices', 'all coin prices'. Rial groups carry *_toman; crypto is USD; unit: mixed adds a unit per row. The crypto preset lists ~27,000 coins unordered: use tj_get_prices or tj_search_symbols.

Inputs: category (required), limit, offset.

tj_get_pricesLive pricesA
Read-onlyIdempotent

Live price, day change, high and low for one or more TGJU symbols.

Use for current rates. Rial symbols also carry *_toman. stale: true = quote older than 2 days. Slugs missing from the live feed answer with their latest daily close (source: history). Unknown ones go to not_found: use tj_search_symbols.

Inputs: symbols (required).

tj_list_categoriesBrowse categoriesA
Read-onlyIdempotent

Browse TGJU's market tree: folders (with ids) and symbols.

Pass a folder id to tj_category_table, or a 'link' item's symbol to tj_get_prices. Top level: 28064 gold, 28066 coin, 28069 currency, 28426 crypto, 28048 precious metals, 28049 oil and energy, 28042 commodities.

Inputs: limit, offset, parent_id.

tj_market_summaryKey rates summaryA
Read-onlyIdempotent

Key Iranian market rates in one call: dollar, euro, gold, coins, ounce, Brent, Bitcoin, Tether.

Use first for 'what are today's rates'. Rial values carry *_toman; ounce, Brent, Bitcoin USD and Ethereum are USD.

Inputs: no named parameters.

tj_price_historyPrice historyA
Read-onlyIdempotent

Daily history (open, low, high, close, change) of a TGJU symbol, for charts and trend questions.

Rows carry Gregorian date and Jalali jalali; Rial symbols also carry *_toman. total = rows in range.

Inputs: symbol (required), limit, offset, to_date, +2 more.

tj_search_symbolsSearch symbolsA
Read-onlyIdempotent

Find TGJU symbols by name.

Use when the symbol is unknown; pass a result's symbol to tj_get_prices or tj_price_history.

Inputs: query (required), limit, scope.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation4/5

    The four price-returning tools operate at different scopes (single/multi symbol, category table, curated market snapshot) and the descriptions explicitly state when to use which, so an agent can pick correctly. The only mild overlap is tj_market_summary vs tj_get_prices for headline rates, and tj_search_symbols vs tj_list_categories as discovery paths, both of which are clarified by 'use first for...' and cross-references.

    Naming Consistency4/5

    All names share a consistent tj_ prefix and snake_case, which makes the set easy to scan. However, the verb style is mixed: some are verb_noun (search_symbols, list_categories, get_prices) while others are noun phrases (category_table, market_summary, price_history).

    Tool Count5/5

    Six tools is right-sized for a read-only market data API: discovery, browsing, bulk quotes, single quotes, a headline snapshot, and history. No tool feels redundant or padded, and no obvious scope is served by a missing tool.

    Completeness4/5

    The surface covers the full read-only lifecycle of price data: symbol discovery, category browsing, current prices, a market overview, and daily history, with clear fallback paths for not_found/stale symbols. Minor gaps exist around intraday/timeframe-granular history and symbol metadata, but the stated purposes (rates, trends, charts) are workable.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Read-only MCP server for Tehran Stock Exchange (TSETMC) live market data and authenticated TSE portal pages, enabling quotes, order books, market watch, and session-safe page reads via natural language.
      11
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables access to Iran Mercantile Exchange official public statistics and live board snapshots through MCP tools, covering physical, futures, options, certificates, salaf, funds, and financial market data.
      14
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to compare cryptocurrency prices, order books, recent trades, candles, and top movers across seven Iranian exchanges in Toman or USDT. Provides read-only, unauthenticated access to public market data from Nobitex, Wallex, Bitpin, Ramzinex, Tabdeal, OMPFinex, and Exir.
      12
      437 PyPI
      12
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to read Tehran Stock Exchange and Iran Fara Bourse market data—quotes, top movers, order books, price history, sector indices, and real vs legal trading—through read-only tools. Requires no API key, returning compact JSON in Rial directly to Claude, Cursor, or Copilot.
      8
      239 PyPI
      7
      MIT