Skip to main content
Glama

psx-mcp

CI PyPI Python License 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

get_quote(symbol)

Current price snapshot for a symbol

get_upcoming_dividends(symbol?)

Payouts table, optionally filtered, with computed buy deadlines

get_buy_deadline(symbol)

Last day to buy and still collect the dividend (T+2 settlement)

get_dividend_history(symbol, years)

Historical payouts

get_announcements(symbol?, limit)

Recent corporate filings + PDF links

search_symbols(query)

Fuzzy match company names → tickers

get_indices()

KSE100, KSE30, KMI30, ALLSHR, PSXDIV20, etc.

get_market_status()

Is PSX open right now? When does it open next?

screen_dividend_stocks(min_payout_pct)

Filter upcoming dividends by payout size

Resources (read-only context)

  • psx://market-status

  • psx://indices

  • psx://upcoming-dividends

Prompts (templated workflows)

  • analyze_dividend_play(symbol) — full dividend-trade analysis

  • portfolio_review(symbols) — review a holdings list

  • find_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.json

  • Windows: %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 8000

The server is then reachable at http://localhost:8000/mcp. Test it with the MCP Inspector:

npx @modelcontextprotocol/inspector
# point it at http://localhost:8000/mcp

Example 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.AsyncClient so MCP calls don't block.

  • Symbol cache. The full PSX symbol list is cached for 24h to make search_symbols fast.

  • Trading-day math. Buy-deadline calculation uses BC_From − 2 trading days, skipping weekends and configurable holidays in dividend_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 dividends

  • psx-cgt-calculator — Pakistan capital-gains-tax with FIFO lots

  • psx-zakat-calculator — zakat on stock holdings (zakatable assets method)

  • psx-broker-statement-parser — normalize KTrade/AKD/JS Global PDFs

  • psx-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_2026 in dividend_calc.py once 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.pk if you need one.

Contributing

  • Add a tool: write the function in scraper.py, expose it in server.py with @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 tools
get_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

    A4.2/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    Nine tools is well-scoped for a stock exchange data server, covering essential functions without being overly numerous or sparse.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      D
      quality
      D
      maintenance
      MCP 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.
      4
      2
      ISC
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that exposes 16 free investment-research signals (insider trades, SEC filings, short data, and live quotes) to any MCP-compatible LLM.
      83 npm
      105
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that exposes stock research tools (fundamentals, news, technicals, analyst ratings) to AI clients, enabling autonomous generation of structured investment briefs.
      -
    • A
      license
      A
      quality
      C
      maintenance
      MCP 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.
      36
      31 npm
      1
      MIT