Skip to content

Releases

0.5.0: fundamentals from Codal, technical indicators, past-day queues

Choose a tag to compare

@msmahdinejad msmahdinejad released this 11 Nov 10:06
02d6373

Fundamental analysis from Codal (45 tools in total): financial statements, monthly activity and fundamentals for industrial companies, banks, insurers and investment companies; technical indicators; market-wide queues of a past day; option chains by Jalali month with covered-call figures.

  • technical_indicators: for one symbol, from its daily prices back-adjusted for capital increases and dividends: SMA 20/50/200, EMA 12/26, RSI 14 (Wilder), MACD 12/26/9 with signal and histogram, Bollinger 20/2 with %B and bandwidth, ATR 14, stochastic 14/3, OBV and its trend, volume against its 20-session average, distance from the 52-week high and low, support and resistance from recent swing lows and highs, the latest MACD/signal and SMA50/SMA200 crosses and a plain-language summary ("RSI 72: overbought", "MACD crossed above signal 2 sessions ago"). The maths lives in the pure module technical.py, tested against hand-computed values; the output says the indicators are computed by the server, not published by the exchange.
  • Queues of a past day: top_movers(kind="buy_queue" | "sell_queue", date=...) returns the queues at the close of that session. Candidates come from the day's end-of-day table of the whole market (last trade at the day's high or low), are checked against that day's official limits and confirmed against the day's order-book history rebuilt at 12:30, with the queue's volume, orders and value at the close, queue_since and held_last_30_minutes. Capped at the 250 largest by traded value, and the output says how candidates were chosen. date is rejected for the other kinds.
  • Empty lists before the open explain themselves: before 09:00 (or while nothing has traded yet today) top_movers, market_watch and screen_stocks say in note that the exchange resets the day's data before the session, name the last trading day and suggest date= for queues. market_watch now always has a note key.
  • Option chains: every expiry in view, and covered calls: option_chain(expiry=...) also takes a Jalali month (9, آذر, برج ۹, 1405/09) and returns every expiry in it. A chain shows expiries_listed and, when it shows only the nearest expiry, an expiry_note naming the others before the strikes, so an agent no longer concludes a later series does not exist. Each call leg has derived covered_call figures: net cost, return if called and if unchanged, annualized return and downside protection. The underlyings list gives expiries_jalali.
  • Bank statements: the bank template (بانک- بورسی) is read with its own lines: loan interest income, deposit interest as the cost of revenue, fee income, loan-loss provisions, customer deposits, loans (government and private rows summed), amounts due to banks and the statutory deposit, with loans_to_deposits_pct and equity_to_assets_pct. A balance sheet with no current/non-current split no longer lists those items as missing. When an interim report leaves the full-year column 0 (banks do), the full year is taken from that year's annual report, so trailing-twelve-month EPS and P/E work: بانک ملت 1405/06/31 gives EPS 601.7 against the exchange's 602. EPS falls back to the net per-share row when the basic-EPS row is 0. Capex and financing lines worded «تحصیل» and «ناشی از» are recognised.
  • Insurer statements: the insurance template (بیمه- بورسی) is read: insurance income as revenue, gross and net premiums, net claims, the gross profit of insurance activities, receivables from policyholders and technical reserves (summed), with loss_ratio_pct. Its balance sheet puts assets and liabilities side by side in one table; such tables are now split in two, so liabilities and equity are read. بیمه البرز 1405/06/31: computed TTM EPS 1171 and P/E 3.82, the exchange's own figures.
  • Bank monthly reports: monthly_activity reads the bank template (گزارش فعالیت ماهانه بانک): realised operating income lines for the month and year to date, loans and deposits at the month end, loans granted and repaid, loan and deposit interest and the net interest of the month. A monthly template with no production-and-sales table (insurers' premiums and claims, investment companies' operating income and portfolio) now returns all its tables plus the month and year-to-date totals of its main table, instead of an empty summary.
  • Contract recorder: --reuse serves requests that already have a recording from disk, so one scenario can be added without refreshing the others; past-day order-book recordings for top_movers keep the rows that rebuild the last minutes of the session.
  • Codal contents and fundamentals (45 tools now): codal_letter reads any Codal letter (financial statements, monthly activity reports, meeting decisions, notices) as tables with parsed numbers or as text; financial_statements returns the income statement, balance sheet and cash flow as key items for this period, the same period last year and the last full year, with margins, growth, ROE/ROA on trailing twelve months and leverage; monthly_activity returns monthly and year-to-date sales by product; fundamentals puts price, statements, computed TTM EPS, P/E, P/S, P/B and recent monthly sales in one call. Subsidiaries filed under the parent's symbol are excluded, and Codal's captcha is detected and reported.
  • Install commands, snippets and one-click links now use PyPI (uvx iran-bourse-mcp) instead of the GitHub URL. IRAN_BOURSE_SOURCE=git+https://github.com/msmahdinejad/iran-bourse-mcp still selects the repository.

Install or update: uvx iran-bourse-mcp@latest install <client>, or restart your agent if it already runs uvx iran-bourse-mcp.

Iran Bourse MCP 0.4.0

Choose a tag to compare

@msmahdinejad msmahdinejad released this 05 Nov 13:39

Iran Bourse MCP 0.4.0

Read-only Tehran Stock Exchange data for any MCP-capable agent, now 40 tools, and the first release published on PyPI.

Website: https://msmahdinejad.github.io/iran-bourse-mcp/

Install

claude mcp add iran-bourse -- uvx iran-bourse-mcp

Recipes and one-click links for 17 agents and IDEs: iran-bourse-mcp config <client> or the README. The older uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp form keeps working.

What's new

  • Commodity and energy exchanges: commodity_market (Iran Mercantile Exchange: physical trades by contract in tons, rial per kilogram and rial, roll-ups, the dollar rate) and energy_market (Iran Energy Exchange: auction results, announced offers, one auction's order levels). Both read the exchanges' public sites, need no account, and state their units per row.
  • Public holidays in market_status: holiday, is_trading_day, next_session (skips weekends and holidays) and upcoming_holidays, from the official 1405 calendar plus the fixed Solar Hijri holidays. A year that is not in the table says so; when the exchange's own data disagrees with the calendar, calendar_check says so.
  • Contract tests: recorded real exchange responses replayed offline exercise every tool through the MCP server layer. They already caught two bugs: market_snapshot listing bonds first, and industry names missing for sector codes 01 to 09.
  • Docs: Persian versions of the data-source and architecture notes, brought up to date with the exchange's market-watch feed and the endpoints behind every tool.
  • Packaging: a slim sdist, a PyPI README with working images and links, and a documented release routine (docs/RELEASING.md).

Requirements and limits

  • Needs an Iranian IP or an in-Iran proxy; iran-bourse-mcp doctor checks connectivity.
  • Unofficial data from public TSETMC, Codal, IME and Energy Exchange endpoints. Not investment advice.
  • Strictly read-only: no orders, no login, no credentials.
  • The holiday table covers Jalali year 1405; the exchange also closes on some days that are not holidays.

Full changelog: CHANGELOG.md

Iran Bourse MCP 0.3.0

Choose a tag to compare

@msmahdinejad msmahdinejad released this 04 Nov 19:59

Iran Bourse MCP 0.3.0

Read-only Tehran Stock Exchange data for any MCP-capable agent, now 38 tools. The headline: a stock screener, the filter box of tsetmc.com driven by your agent.

Website: https://msmahdinejad.github.io/iran-bourse-mcp/

You:    stocks whose volume today is over twice their 20-day average, that rose more than 1% yesterday,
        are positive today, and trade over 5 billion rial
Agent:  screen_stocks(filter="volume > 2 * avg(volume, 20) and close_pct[1] > 1 and close_pct > 0 and value > 5B")

One call, only the stocks that pass right now, with the numbers behind each hit. On the live exchange the same screen took 22 requests and 7.4M raw tokens through plain HTTP, and 1 call and 723 tokens through the server (small, single-model benchmark; method and limits in benchmarks/README.md).

Install

claude mcp add iran-bourse -- uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp

Recipes and one-click links for 17 agents and IDEs: iran-bourse-mcp config <client> or the README.

What's new

  • Stock screener (screen_stocks, screener_reference, prompt find_stocks): a safe expression language (parsed, never executed) over every instrument, with today's live values, up to 60 past trading days adjusted for capital increases (close[1], avg(volume, 20), count(close_pct > 0, 5), highest(high, 10)), real/legal flow, a five-level order book, base volume, fund NAV and open interest. Accepts the field names of the tsetmc filter box, ships 15 presets and explains mistakes with suggestions. Guide: docs/SCREENER.md.
  • Derivatives: option_chain (by strike and expiry, moneyness, time value, break-even, put/call ratios, estimated max pain) and futures_market (with basis).
  • Indices and funds: index_history (daily since 2008 or today's 5-minute path), index_constituents (effect in index points), fund_ranking (579 funds).
  • Exchange lists and calendar: top_lists (69 official best-of lists), capital_calendar (upcoming capital increases), trading_status (suspended and supervised symbols).
  • Wider data: the market tools now run on the exchange's own feed, about 3,700 instruments instead of 582 shares. Weekly/monthly/yearly price bars, per-holder shareholder history, industry-level real money flow, new glossary terms.
  • Fixes from two independent client reviews (a Codex client and an agent calling the server over stdio, 117 questions, every number recomputed from raw exchange data): buy/sell queues no longer break on orders priced outside the day's limits, duplicate tickers resolve to the live record, Codal title filters read further pages, HTTP 429 is reported as rate limiting, and more. See the changelog.
  • Screener results match an independent re-implementation from raw data on three screens (29/29, 14/14, 32/32). 584 offline tests, 92% line coverage.

Requirements and limits

  • Needs an Iranian IP or an in-Iran proxy; iran-bourse-mcp doctor checks connectivity.
  • Unofficial data from public TSETMC/Codal endpoints. Not investment advice.
  • Strictly read-only: no orders, no login, no credentials.
  • The filter language is this project's own; it borrows names from the tsetmc filter box but filters are not copy-compatible in both directions.

Full changelog: CHANGELOG.md

Iran Bourse MCP 0.2.0

Choose a tag to compare

@msmahdinejad msmahdinejad released this 04 Nov 09:37

Iran Bourse MCP 0.2.0

Read-only Tehran Stock Exchange data for any MCP-capable agent: 28 tools, 3 prompts and a glossary resource, covering quotes, order book (live and rebuilt history), tick-by-tick trades, real/legal money flow, major shareholders, corporate actions, adjusted price history, fund NAV and Codal filings.

Website: https://msmahdinejad.github.io/iran-bourse-mcp/

Install

claude mcp add iran-bourse -- uvx --from git+https://github.com/msmahdinejad/iran-bourse-mcp iran-bourse-mcp

Recipes and one-click links for 17 agents and IDEs (Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor, VS Code, Windsurf, Cline, Roo Code, Kiro, Qwen Code, JetBrains, Zed, OpenCode, Goose, Amp, any MCP client): iran-bourse-mcp config <client> or the README.

What's new

  • Fix: queue and real-money rankings in top_movers returned nothing during the session, because today's end-of-day table is empty until the close. The instrument index now falls back to the newest published day.
  • Fix: gateway failures (502/503) are retried more patiently and reported as an overloaded exchange, not as an IP problem.
  • CLI: tools, call (every tool from the shell, for agents without MCP), config <client>, install <client> (safe merge with backup).
  • Docs and site: GitHub Pages website with a promo video, animated README artwork, Persian guide, tool reference, real example outputs.
  • Benchmarks: reproducible harness with independent ground truth. On the live exchange: a day of ticks 2,142,302 → 3,380 tokens; a market-wide buy-queue ranking 222 requests → 1 tool call; agent answers 99% correct with the server vs 21% for a browser-only agent. The benchmark is small and single-model, and the shell agent already knew the endpoints; see benchmarks/README.md for method and limits.
  • Project: container image, AGENTS.md, llms.txt, code of conduct, citation file, dependabot. 142 offline tests, 89% line coverage.

Requirements and limits

  • Needs an Iranian IP or an in-Iran proxy; iran-bourse-mcp doctor checks connectivity.
  • Unofficial data from public TSETMC/Codal endpoints. Not investment advice.
  • Strictly read-only: no orders, no login, no credentials.
  • Order-book history for the current day is partial (upstream delta feed).

Full changelog: CHANGELOG.md

Launch film (2 min)

Choose a tag to compare

@msmahdinejad msmahdinejad released this 04 Nov 23:30

The 2-minute launch film for iran-bourse-mcp: an AI agent reads the Tehran Stock Exchange through the MCP server. A buy queue in one call, every Foolad trade of a single minute, and a market-wide screen that costs about 10,000 times fewer tokens. Persian narration, English and Persian subtitles.

Watch it on the site: https://msmahdinejad.github.io/iran-bourse-mcp/#film

Free to download and share.

16:9 9:16
Web and social (about 20 MB) iran-bourse-mcp-film-16x9-social.mp4 iran-bourse-mcp-film-9x16-social.mp4
Full HD (1920x1080, 1080x1920) iran-bourse-mcp-film-16x9-1080p.mp4 iran-bourse-mcp-film-9x16-1080p.mp4
4K master (3840x2160, 2160x3840) iran-bourse-mcp-film-16x9-4k.mp4 iran-bourse-mcp-film-9x16-4k.mp4

Subtitles: captions.fa.srt (Persian), captions.en.srt (English).

About the numbers: every figure on screen is real tool output captured on 4 Nov 2026 with the market closed ("today" is the session of 1405/08/13). The benchmark in the film (22 requests and about 7.4 million tokens against 1 call and 723 tokens) is small and single-model. The music is synthesised; the assistant window is a neutral mock-up, not a real product's interface.


فیلم ۲ دقیقه‌ایِ معرفیِ ام‌سی‌پیِ بورسِ ایران (iran-bourse-mcp) با روایتِ فارسی و زیرنویس فارسی و انگلیسی. دانلود و انتشارش آزاد است. نسخهٔ وب و شبکه‌های اجتماعی حدود ۲۰ مگابایت است؛ فول‌اچ‌دی و 4K هم در همین صفحه هست، افقی ۱۶:۹ و عمودی ۹:۱۶. هر عددی که در فیلم می‌بینید خروجی واقعیِ ابزار است (۱۴۰۵/۰۸/۱۳، بازار بسته بود)، و بنچمارکِ فیلم کوچک و تک‌مدلی است.