Skip to main content
Glama

bource-mcp

Read-only MCP bridge for the Iran Bourse. Live Tehran Stock Exchange (TSETMC) market data + a hard-guarded, authenticated session for TSE portal pages — installable in one command, wired straight into opencode (or any MCP client).

HTTP/GET only. No write tools exist. The browser guard aborts every non-GET request client-side. This bridge is built to read the market and your portal pages — it cannot place orders, cancel, transfer, or change anything. That is a design property, not a promise.


Install (one command)

Requires Node.js ≥ 18 (Windows path used here: C:\Users\User\tools\node\node.exe).

powershell -ExecutionPolicy Bypass -File install.ps1

Or after the repo is public on GitHub:

irm https://raw.githubusercontent.com/a-saeedia/bource-mcp/main/install.ps1 | iex

What it does:

  1. npm install (SDK + Playwright)

  2. Downloads Playwright Chromium (one-time, ~150 MB; skip with -SkipBrowser)

  3. Auto-registers the bource MCP server into your global opencode config (~/.config/opencode/opencode.jsonc), with a backup of your previous config

  4. Installs a global /bourse opencode command that drops you straight into the market prompt

Then: restart opencode → /mcp shows bource connected → type /bourse or just ask "is the Tehran market open?".

Manual registration (any MCP client):

"mcp": {
  "bource": {
    "type": "local",
    "command": ["C:\\Users\\User\\tools\\node\\node.exe", "C:\\path\\to\\bource-mcp\\server.js"],
    "enabled": true
  }
}

Related MCP server: tsetmc-mcp

Tools

Tool

What it does

market_status

Is the Tehran market open (Sat–Wed 09:00–12:30 Asia/Tehran)

search_symbol

Symbol/name search (فملی، خودرو، …) → insCode

get_quote

Live quote, % change, bid/ask, trades (Rial) + freshness stamp

get_order_book

صف خرید/فروش order book

get_money_flow

حقیقی/حقوقی retail/institutional flow

get_price_history

Daily OHLCV history

get_market_watch

Whole-market snapshot (prefer over per-symbol loops)

get_index_overview

Index/market overview (bourse / fara-bourse)

session_status

Which portal sessions exist (never shows credentials)

page_open

Open TSE portal page with saved read-only session

page_read

Extract readable text/tables from the open portal page


Authenticated portal pages (your account)

The model never handles credentials. Once:

npm run login

…opens a headed browser to https://my.tsetmc.com (override with BOURCE_PORTAL_URL). You log in with your own OTP/credentials, press Enter, and the cookies are stored encrypted (AES-256-GCM, key in BOURCE_DATA_DIR). From then on page_open / page_read use that session — with every non-GET request aborted at the browser level and navigation restricted to the exchange allowlist.


Read-only enforcement (layered)

  1. Tool surface — only read tools are registered; the registry guard refuses any non-allowlisted name. No order_*/trade_* code exists.

  2. HTTP guard — every upstream call rejects non-GET/HEAD.

  3. Browser guard — Playwright route interception aborts POST/PUT/PATCH/ DELETE; downloads cancelled.

  4. Allowlist — browser navigation only to my.tsetmc.com, tsetmc.com, tse.ir, webgw.tse.ir (env BOURCE_ALLOW_HOSTS).

  5. Secrets hygiene — encrypted session store; redaction strips tokens, cookies, and hex blobs from everything the model sees.

See SECURITY.md for the full threat model.


Operational notes (from field experience)

  • Run it in Iran. cdn.tsetmc.com favors Iranian IPs and soft-blocks foreign/VPN ones. From outside Iran you need an in-Iran relay.

  • Market hours Sat–Wed 09:00–12:30 (Asia/Tehran). Outside that, live quotes are empty — every response is freshness-stamped so stale data is never mistaken for live.

  • Rate limits: the cache + bulk endpoints (get_market_watch) exist so you don't hammer TSETMC. Keep per-symbol calls sparse.

  • Prices are in Rial.

  • No API key. Unofficial public API — use responsibly; check TSE terms.


Roadmap

  • v0.1 TSE foundation: market data + guarded portal session

  • v0.2 Structured portfolio extractors (positions / wallet / orders history) once the portal schema is confirmed

  • v0.3 Saman exchange adapter (same read-only contract)

  • v0.4 Fid (فید) exchange adapter (same read-only contract)

New exchange adapters implement the same guard layers: read tools only, GET-only HTTP, browser allowlist, encrypted sessions.

License

MIT — build on it, fork it, ship it. See LICENSE.

Available Tools

11 tools
get_index_overviewB

Market overview / index values (flow 1 = bourse, 2 = fara-bourse).

Inputs: flow.

get_market_watchB

Whole-market snapshot (market=0 all, 1 bourse, 2 fara-bourse, 4 payeh). Prefer this over per-symbol loops.

Inputs: top, flow.

get_money_flowB

حقیقی/حقوقی (retail/institutional) money-flow summary for an instrument by insCode.

Inputs: insCode (required).

get_order_bookB

5-level order book (صف خرید/فروش) for an instrument by insCode.

Inputs: insCode (required).

get_price_historyB

Daily OHLCV history (Rial) for an instrument by insCode. Fresh full-market pull is cached 1h.

Inputs: insCode (required), top.

get_quoteA

Live quote for an instrument by insCode (Rial). Stamped with freshness: market_open + staleness_seconds.

Inputs: insCode (required).

market_statusA

Is the Tehran market open right now (Sat–Wed 09:00–12:30 Asia/Tehran)? Local, no network.

Inputs: no named parameters.

page_openB

Open a page on the TSE/TSETMC portal with the saved read-only session. Non-GET requests are blocked.

Inputs: url (required), waitMs.

page_readB

Extract readable text (and tables as text) from the currently open portal page. Truncated to maxChars.

Inputs: maxChars, selector.

search_symbolA

Search a TSETMC instrument by Persian/English symbol or name (e.g. "فملی", "خودرو", "farda"). Returns insCode + market.

Inputs: query (required).

session_statusA

Which authenticated portal sessions exist (never exposes credentials) and the browser allowlist.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct operation: market timing, symbol lookup, single-instrument quotes, order book depth, money flow, price history, whole-market snapshots, index overview, session info, and portal page navigation/reading. There is no meaningful overlap; even get_quote and get_market_watch are clearly scoped as single-symbol vs whole-market.

    Naming Consistency4/5

    Most tools follow a predictable get_<noun> or page_<verb> pattern, with search_symbol also matching action_noun structure. market_status and session_status are minor deviations, but they form a consistent status-noun pair and do not create confusion.

    Tool Count5/5

    11 tools is well within the ideal range and each tool earns its place by covering a distinct aspect of Tehran market data plus portal browsing. There is no bloat or unnecessary redundancy.

    Completeness5/5

    The tool surface covers the full read-only workflow: symbol discovery, quote, depth, money flow, history, market-wide snapshot, index overview, and portal page access. No obvious dead ends or missing core operations for the stated TSE/TSETMC market data purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Real-time financial market data MCP server. Stocks, crypto, technicals, sentiment, FDA calendar. No API keys required.
      -
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that provides live Tehran Stock Exchange data, including quotes, order books, money flow, and custom filters, to Claude and other MCP clients.
      13
      4
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Read-only MCP server for accessing Spark/Ordernet brokerage accounts, including Meitav Trade, Psagot, IBI, Nesua, and Gaon. Enables querying holdings, transactions, orders, returns, security lookup, price history, standing orders, and market news 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