Psx Server

CI PyPI Python License: MIT

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

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 [email protected]. Nothing here is investment advice.

License

MIT © Ahmed Raza