psx-mcp
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., "@psx-mcp List upcoming dividends with payout above 50%"
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.
psx-mcp
mcp-name: io.github.revolutionarybukhari/psx-mcp
Talk to the Pakistan Stock Exchange in plain English.
psx-mcp is a Model Context Protocol server that exposes PSX market data — quotes, dividends, announcements, indices — as tools any MCP-compatible AI client can call. Connect it to Claude Desktop, Cursor, ChatGPT, or your own agent, and ask questions like:
"What are the upcoming dividends on PSX with payouts above 100%?"
"Should I buy MEBL today to collect the dividend?"
"Pull recent announcements for OGDC and summarize anything material."
"How has FFC's dividend history looked over the past 5 years?"
The LLM picks the right tools automatically and answers in your language.
Why MCP?
Existing PSX tools are libraries — you import them, write code, get data. MCP servers are tools an LLM calls for you. You ask in English, the model invokes get_quote, get_upcoming_dividends, get_dividend_history, and synthesizes an answer. No Python required for the end user.
This is also the first PSX MCP server published. If you're building agents, financial copilots, or AI-augmented research workflows for Pakistani markets, this gives them eyes.
Related MCP server: OpenInsider MCP
What's exposed
Tools (LLM-callable)
Tool | What it does |
| Current price snapshot for a symbol |
| Payouts table, optionally filtered, with computed buy deadlines |
| Last day to buy and still collect the dividend (T+2 settlement) |
| Historical payouts |
| Recent corporate filings + PDF links |
| Fuzzy match company names → tickers |
| KSE100, KSE30, KMI30, ALLSHR, PSXDIV20, etc. |
| Is PSX open right now? When does it open next? |
| Filter upcoming dividends by payout size |
Resources (read-only context)
psx://market-statuspsx://indicespsx://upcoming-dividends
Prompts (templated workflows)
analyze_dividend_play(symbol)— full dividend-trade analysisportfolio_review(symbols)— review a holdings listfind_dividend_opportunities(min_payout_pct)— screener + per-name analysis
Install
Requires Python 3.10+.
# From PyPI (once published)
pip install psx-mcp
# Or with uv (recommended)
uv tool install psx-mcp
# From source
git clone https://github.com/revolutionarybukhari/psx-mcp
cd psx-mcp
pip install -e .Connect to Claude Desktop
Edit your Claude Desktop config:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"psx": {
"command": "uvx",
"args": ["psx-mcp"]
}
}
}Restart Claude Desktop. You should see the PSX tools listed in the connection icon. Try:
"What dividends are coming up this week on PSX?"
Connect to Cursor
Settings → MCP → add server:
{
"mcpServers": {
"psx": {
"command": "psx-mcp",
"args": []
}
}
}Run as remote HTTP server
For shared/team use or hosted agents:
psx-mcp --transport http --host 0.0.0.0 --port 8000The server is then reachable at http://localhost:8000/mcp. Test it with the MCP Inspector:
npx @modelcontextprotocol/inspector
# point it at http://localhost:8000/mcpExample prompts to try
Once connected:
"List all PSX stocks paying more than 50% dividend right now,
sorted by buy deadline."
"For each stock in my portfolio (HBL, OGDC, PSO, ENGRO, MEBL),
tell me if there's an upcoming dividend and what the buy deadline is."
"Find me consistent dividend payers on PSX — companies that have
paid every year for the last 3+ years with payouts above 30%."
"What's happening with FFC today? Pull the quote and the latest
3 announcements."
"Walk me through the dividend trade for MARI step by step."How it works
┌──────────────────────┐ ┌─────────────────┐
│ Claude / Cursor / │ MCP │ psx-mcp │
│ ChatGPT / Agent │ ──────► │ server │
└──────────────────────┘ └────────┬────────┘
│ httpx + bs4
▼
┌─────────────────┐
│ dps.psx.com.pk │
└─────────────────┘Tools call the public PSX Data Portal, parse HTML with BeautifulSoup, normalize into structured JSON, and return to the LLM. No keys, no auth, no scraping headaches for the consumer.
Architecture notes
Async everywhere. All scraper functions use
httpx.AsyncClientso MCP calls don't block.Symbol cache. The full PSX symbol list is cached for 24h to make
search_symbolsfast.Trading-day math. Buy-deadline calculation uses
BC_From − 2 trading days, skipping weekends and configurable holidays individend_calc.PSX_HOLIDAYS_2026.No persistence. This server is stateless. State (alerts, watchlists) belongs in your client.
Pairs well with
This is one server in a wider PSX open-source toolkit:
psx-dividend-alert— proactive Telegram alerts for upcoming dividendspsx-cgt-calculator— Pakistan capital-gains-tax with FIFO lotspsx-zakat-calculator— zakat on stock holdings (zakatable assets method)psx-broker-statement-parser— normalize KTrade/AKD/JS Global PDFspsx-announcements-summarizer— LLM-powered summaries of every PSX filing
The MCP server makes all of these LLM-callable. Pair them and you have a complete conversational PSX research stack.
Limitations / honest notes
PSX data is delayed ~5 minutes. Same as the public Data Portal.
Scraping is fragile. If PSX changes their HTML, parsers will need updating. PRs welcome.
No order placement. This is read-only. There's no path here that puts trades on the wire — by design.
Holiday list is stub. Edit
PSX_HOLIDAYS_2026individend_calc.pyonce PSX publishes the annual calendar. Without it, the buy-deadline math correctly skips weekends but will be off during Eid/Independence Day weeks.Personal use. PSX terms restrict commercial redistribution of market data without a license. Email
marketdatarequest@psx.com.pkif you need one.
Contributing
Add a tool: write the function in
scraper.py, expose it inserver.pywith@mcp.tool(), add a docstring (the docstring becomes the LLM's tool description — make it clear).Add a test: drop async tests in
tests/. The MCP SDK supports in-memory testing.File issues for HTML parser breakage with the failing URL and a snippet.
License
MIT. See LICENSE.
Available Tools
9 toolsget_announcementsA
Get recent corporate announcements from PSX.
Args: symbol: Optional ticker filter (e.g. only OGDC announcements). limit: Max rows to return (default 20, cap 100).
Each item includes date, symbol, title, and a PDF link to the original notice.
Inputs: limit, symbol. Returns: result
get_buy_deadlineA
For a symbol with an upcoming dividend, return the last day you can buy and still be entitled to the dividend (T+2 settlement applied).
Returns 'no upcoming dividend' if the symbol isn't currently in the PSX payouts table.
Inputs: symbol (required).
get_dividend_historyA
Get historical dividend payouts for a symbol.
Args: symbol: PSX ticker. years: How many years of history to return (default 5).
Inputs: symbol (required), years. Returns: result
get_indicesA
Get current values for major PSX indices: KSE100, KSE30, ALLSHR, KMI30, KMIALLSHR, PSXDIV20, BKTI, OGTI, MII30.
Inputs: no named parameters. Returns: result
get_market_statusA
Is PSX open right now? Returns OPEN / PRE_OPEN / CLOSED_TODAY / WEEKEND plus the next market open in PKT.
Inputs: no named parameters.
get_quoteA
Get the current price quote for a PSX-listed symbol.
Args: symbol: PSX ticker, e.g. "MEBL", "OGDC", "FFC", "ENGRO".
Returns last price, change, change %, volume, day high/low, open, prev close. Data is delayed by 5 minutes per PSX Data Portal.
Inputs: symbol (required).
get_upcoming_dividendsA
List upcoming dividend payouts on PSX.
Args: symbol: Optional PSX ticker to filter. If omitted, returns all upcoming payouts in the table.
Each result includes book closure dates, AGM date, payout amount/type, and the computed buy deadline (T+2 settlement) — the last day you can buy and still be entitled to the dividend.
Inputs: symbol. Returns: result
screen_dividend_stocksA
Screen the upcoming-payouts table by payout size.
Args: min_payout_pct: Minimum payout % to include (e.g. 50 = 50% of par). PSX payouts are quoted as % of face value (typically Rs 10). limit: Max results.
NOTE: This is a payout-size filter, not a true dividend-yield screen (yield = dividend / current price). For real yield you'd cross-reference each symbol's current price — call get_quote() per symbol if needed.
Inputs: limit, min_payout_pct. Returns: result
search_symbolsA
Fuzzy search PSX symbols and company names.
Useful when the user names a company casually ("habib bank" -> "HBL", "fauji fertilizer" -> "FFC").
Inputs: query (required), limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct aspect of PSX data: announcements, dividends (various forms), indices, market status, quotes, and symbol search. No two tools have overlapping purposes.
Most tools follow a 'get_' prefix (get_announcements, get_quote, etc.), but 'screen_dividend_stocks' and 'search_symbols' use different verbs. The pattern is mostly consistent with minor deviations.
Nine tools is well-scoped for a stock exchange data server, covering essential functions without being overly numerous or sparse.
The tool set covers quotes, indices, market status, dividends (history, upcoming, screening, buy deadline), announcements, and symbol search. Missing historical prices or detailed corporate actions, but adequate for typical queries.
Maintenance
Related MCP Connectors
MCP server exposing the Backtest360 engine API as tools for AI agents.
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
Financial data MCP server for Claude, ChatGPT, Cursor and Codex. Real-time stock quotes, financial statements, options flow, SEC filings, insider trades, 13F holdings, macro data and market news from gloom.sh, the open-source Bloomberg Terminal alternative.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Related MCP Servers
- AlicenseDqualityDmaintenanceMCP server that exposes Alpaca Market Data & Broker API as tools, enabling access to financial data like stock bars, assets, market days, and news through the Message Control Protocol.42ISC
- AlicenseNot gradedqualityCmaintenanceAn MCP server that exposes 16 free investment-research signals (insider trades, SEC filings, short data, and live quotes) to any MCP-compatible LLM.83 npm105MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that exposes stock research tools (fundamentals, news, technicals, analyst ratings) to AI clients, enabling autonomous generation of structured investment briefs.-

siftingio-mcpofficial
AlicenseAqualityCmaintenanceMCP server that provides access to SiftingIO market data, including live prices, SEC filings, OHLCV bars, 13F holdings, market status, and economic calendar tools for AI assistants.3631 npm1MIT