bource
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bource is the Tehran market open right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.ps1Or after the repo is public on GitHub:
irm https://raw.githubusercontent.com/a-saeedia/bource-mcp/main/install.ps1 | iexWhat it does:
npm install(SDK + Playwright)Downloads Playwright Chromium (one-time, ~150 MB; skip with
-SkipBrowser)Auto-registers the
bourceMCP server into your global opencode config (~/.config/opencode/opencode.jsonc), with a backup of your previous configInstalls a global
/bourseopencode 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 |
| Is the Tehran market open (Sat–Wed 09:00–12:30 Asia/Tehran) |
| Symbol/name search (فملی، خودرو، …) → |
| Live quote, % change, bid/ask, trades (Rial) + freshness stamp |
| صف خرید/فروش order book |
| حقیقی/حقوقی retail/institutional flow |
| Daily OHLCV history |
| Whole-market snapshot (prefer over per-symbol loops) |
| Index/market overview (bourse / fara-bourse) |
| Which portal sessions exist (never shows credentials) |
| Open TSE portal page with saved read-only session |
| 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)
Tool surface — only read tools are registered; the registry guard refuses any non-allowlisted name. No
order_*/trade_*code exists.HTTP guard — every upstream call rejects non-GET/HEAD.
Browser guard — Playwright route interception aborts POST/PUT/PATCH/ DELETE; downloads cancelled.
Allowlist — browser navigation only to
my.tsetmc.com,tsetmc.com,tse.ir,webgw.tse.ir(envBOURCE_ALLOW_HOSTS).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.comfavors 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 toolsget_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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
A Model Context Protocol server exposing real-time and historical Colombo Stock Exchange (CSE) data to AI agents and LLM applications. Provides quotes and OHLCV price history, full financial statements (income, balance sheet, cash flow), pre-computed technicals (moving averages, RS ratings, volume signals), macroeconomic indicators, corporate actions, and rule-based screening across CSE stocks and sector indices, everything needed to build CSE-aware trading assistants, research tools, and market-analysis agents. This is the official MCP server of www.ceyloncharts.com
Read-only MCP server for Belarusian securities: tokens, shares, bonds, companies.
Hosted MCP server for Indian market quotes, option-chain Greeks and multi-broker telemetry.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceReal-time financial market data MCP server. Stocks, crypto, technicals, sentiment, FDA calendar. No API keys required.-
- AlicenseAqualityDmaintenanceAn MCP server that provides live Tehran Stock Exchange data, including quotes, order books, money flow, and custom filters, to Claude and other MCP clients.134MIT
- AlicenseBqualityDmaintenanceRead-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.111MIT
- AlicenseBqualityCmaintenanceEnables 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.14MIT