tgju-mcp
Advanced tools
Unofficial read-only MCP server for TGJU (tgju.org): live Iranian gold, coin, currency and crypto prices, daily history.
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
uvx tgju-mcp or claude mcp add tgju -- uvx tgju-mcp. Transport: stdio. Needs uv (Python 3.10+).TGJU_MCP_PROXY (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.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.*_toman (Rial / 10). Global symbols (ounce, Brent, crypto in USD, currency pairs) keep their listed unit (unit: as_listed).server.json and the
iran-mcp catalog.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_historyIt 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.
Example prompts:
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.
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.
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.
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: mixed); symbols outside it, such as exchange-house quotes with slug names, stay as_listed.tj_category_table and tj_price_history return at most 50 rows, so replies stay under about 14 KB.stale: true. Illiquid symbols can be delayed, so check time.tj_search_symbols) are answered by tj_get_prices with the latest daily close (source: history, time = date).from_date and to_date filters are Jalali YYYY/MM/DD.TGJU_MCP_PROXY. System proxy variables are ignored on purpose.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
| 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 |
tgju-mcp یک سرور MCP غیررسمی و فقطخواندنی برای سایت TGJU (شبکه اطلاعرسانی طلا، سکه و ارز) است. این سرور به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه میدهد قیمت دلار، یورو، طلا، سکه، ارز دیجیتال و کالاها را از tgju.org بخواند.
چه کارهایی میکند
نکتهها
time را ببینید.TGJU_MCP_PROXY را بگذارید.نصب (اول uv را نصب کنید). در Claude Code:
claude mcp add tgju -- uvx tgju-mcp
در Claude Desktop، Cursor و بقیه برنامهها همان تنظیم بخش Quick start را بگذارید.
نمونه پرسشها
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.
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.
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.
FAQs
Unofficial read-only MCP server for TGJU (tgju.org): live Iranian gold, coin, currency and crypto prices, daily history.
We found that tgju-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.