psx-mcp-server 0.1.0

Model Context Protocol server for the Pakistan Stock Exchange — live quotes, EOD history, indices, fundamentals, dividends, and announcements as LLM-callable tools.

psx-mcp-server

A Model Context Protocol server that gives Claude and other MCP agents live Pakistan Stock Exchange data — quotes, intraday and end-of-day history, indices (KSE-100 and 17 others), company fundamentals, dividends, and announcements — sourced from the public PSX Data Portal. No API key required.

Quick start

The server runs via uv — uvx fetches and runs it in one step, so there is nothing to install manually.

Claude Code:

claude mcp add psx -- uvx psx-mcp-server

Claude Desktop — add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "psx": {
      "command": "uvx",
      "args": ["psx-mcp-server"]
    }
  }
}

Any MCP client: run uvx psx-mcp-server (stdio transport). Requires uv (install guide).

Example

You: Which PSX stocks gained the most today, and what's HBL trading at?

The agent calls get_market_snapshot and get_quote, and answers:

TOP 5 GAINERS:
  TCORPR2  +22.62%  Rs.5.42
  PINL     +10.52%  Rs.10.51
  HICL     +10.05%  Rs.11.50
  TSPL     +10.02%  Rs.18.12
  CLVL     +10.02%  Rs.22.41
  breadth: 296 advancers / 180 decliners

HBL: Habib Bank Limited | current Rs.318.15 | P/E 7.43
KSE100: 187,454.69 (+1.12%)

Tools

Tool	Parameters	Returns
search_symbols	query, sector?, limit=20	Matching tickers (exact matches first). Use first if unsure of a ticker.
get_quote	symbol	Current price, LDCP, OHL, change %, volume, bid/ask, 52-week range, P/E (PKR).
get_intraday	symbol, interval="5min", limit=50	Intraday OHLCV bars (or raw ticks) for the latest session, PKT times.
get_eod_history	symbol, start_date?, end_date?, limit=260	Daily open/close/volume (~5 yrs). Works for indices. No high/low.
get_ohlc_history	symbol, month, year	Full daily OHLCV for one month — the only free source of daily high/low.
get_market_snapshot	category="gainers", limit=15, sector?	Top movers (gainers/losers/volume) plus market breadth.
get_indices	—	All ~18 PSX indices with change %.
get_company_info	symbol	Business description, sector, market cap, shares, free float, P/E.
get_dividends	symbol, limit=10	Payout history (cash/bonus/rights) with book-closure dates.
get_announcements	symbol, limit=10	Recent corporate announcements with document (PDF) links.

Resources: psx://symbols (full ticker directory), psx://sectors (sector names), psx://indices (current index values).

Prompts: analyze_stock(symbol) (single-stock research brief), market_overview() (today's market wrap).

Notes

• Prices are in PKR; timestamps are Pakistan Standard Time (UTC+5, no DST).
• PSX trades Monday–Friday, ~09:30–15:30 PKT. Outside those hours, quotes reflect the last session and intraday data may be empty.
• Responses are cached briefly (30 s intraday … 24 h for the symbol directory) to be polite to the portal. Override the request identity with the PSX_MCP_USER_AGENT environment variable.

Development

git clone https://github.com/ahmedraza-96/psx-mcp-server
cd psx-mcp-server
uv sync

uv run pytest                 # unit tests (mocked, offline)
uv run ruff check . && uv run ruff format --check .

# Live tests hit the real portal — run during PKT market hours:
uv run pytest -m live --override-ini "addopts="

# Re-record test fixtures if PSX changes its markup:
uv run python scripts/record_fixtures.py

Architecture: parsers/ are pure functions (raw response in, dataclasses out) tested against committed fixtures in tests/fixtures/; client.py owns all HTTP I/O (caching, retries, error mapping); tools.py composes the two into MCP tools. See CHANGELOG.md for release history.

Disclaimer

This is an unofficial project and is not affiliated with or endorsed by the Pakistan Stock Exchange. Data comes from the public PSX Data Portal (dps.psx.com.pk) and may be delayed or inaccurate. For licensed or commercial market data, contact [e-mail]. Nothing here is investment advice.

License

MIT © Ahmed Raza