PSX MCP server

A remote MCP connector that gives Claude live Pakistan Stock Exchange data: prices, market summary, top movers, company fundamentals, price history with indicators, dividends, announcements, index members and sectors.

Data comes from the public PSX Data Portal (dps.psx.com.pk). This is for personal use. Redistributing PSX market data needs a PSX licence.

See PRIVACY.md for what data this server processes, and LICENSE for the code's licence (MIT; separate from PSX's own licensing terms on the underlying data).

Tools

Related MCP server: Indonesian Stock Analysis MCP Server

How it talks to PSX

The portal's data endpoints only answer browser AJAX calls. They need X-Requested-With: XMLHttpRequest plus an X-Req-Id token that the portal embeds in its HTML (window.__ps._k). The client fetches that token from the homepage, refreshes it on a 403, paces requests (0.35 s apart, 2 at a time), retries 503s, and caches results (30 s for prices, 1 h for daily history, 24 h for the symbol list). If PSX changes its page layout, fixes go in psx_mcp/parsers.py.

Deploy on Vercel (free, no card)

1. Push this folder to a GitHub repo (public or private both work; nothing secret is committed — MCP_SECRET is set as an env var, never in code).

2. vercel.com → Add New… → Project → import the repo. Leave build settings as detected.

3. Add environment variable MCP_SECRET (32+ letters/digits), then Deploy.

4. Check https://<project>.vercel.app/health.

5. Connector URL: https://<project>.vercel.app/<MCP_SECRET>/mcp

vercel.json pins the function to Singapore (sin1). PSX's firewall (DOSarrest) returns "462 Forbidden Region" to Indian IPs, so avoid bom1. app.py is the Vercel entrypoint; it serves MCP statelessly, one request at a time.

Deploy on Render (free)

1. Create a GitHub repo (for example psx-mcp, public or private) and upload everything in this folder.

2. On render.com, choose New → Blueprint, pick the repo, and Render reads render.yaml (Singapore region, free plan).

3. When it asks for MCP_SECRET, paste a long random string (32+ letters and digits, no /).

4. After the deploy goes green, open https://<your-app>.onrender.com/health. It should show {"status":"ok"}.

5. Your connector URL is: https://<your-app>.onrender.com/<MCP_SECRET>/mcp

Connect to Claude

Go to claude.ai → Settings → Connectors → Add custom connector. Name it PSX, paste the connector URL, and leave OAuth empty. In a chat, enable the connector and ask Claude to run psx_selftest. All 16 checks should pass.

Treat the connector URL like a password, since anyone with it can use your server.

Things to know

• Single-tenant by design: this is built for one person's own deployment with one shared secret, not a multi-tenant public service. All requests from a deployment leave from the same IP and share one in-memory cache; if many people used the same instance, PSX could rate-limit or block that IP for everyone. Don't share a deployed connector URL widely.

• Cold starts: Render's free plan sleeps after about 15 minutes idle. The first call after that can take 30 to 60 seconds, and Claude may time out once. Retry, or upgrade to the Starter plan to keep it awake.

• IP blocking: if psx_selftest shows the token or market watch failing with 403s, PSX is blocking the host's IP. Try another region or host. Running locally on a Pakistani connection always works.

• Accuracy: the numbers are PSX's own. The portal can lag the live feed by a little. Tool output is data, not investment advice.

Run locally / test

pip install -r requirements-dev.txt
pytest -q tests                      # uses saved fixtures, no network
MCP_SECRET=local-dev-secret-123456 python -m psx_mcp.server
# connector URL: http://localhost:8000/local-dev-secret-123456/mcp