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

Watchlist, alerts and insider/corporate activity (needs a database)

These persist to Postgres instead of just reading PSX; see Watchlist and alerts setup below before using them.

Note: insider_activity/corporate_actions default to your watchlist when no symbols are given. There's no persisted portfolio yet (psx_portfolio takes holdings as a call-time argument and stores nothing), so they can't default to "portfolio + watchlist" until that exists.

Related MCP server: PSX MCP

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. For the watchlist/alerts tools, also add DATABASE_URL, CRON_SECRET and the TELEGRAM_* vars -- see Watchlist and alerts setup below.

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 /). For the watchlist/alerts tools, also set DATABASE_URL, CRON_SECRET and the TELEGRAM_* vars -- see Watchlist and alerts setup below.

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

Watchlist and alerts setup

The watchlist/alerts/insider/corporate-actions tools need a Postgres database and, for Telegram delivery, a bot. Skip this section if you only want the read-only PSX tools above — everything else works without it (and psx_selftest will just report those checks as failing, not crash).

1. Database. On Vercel, add Neon Postgres from the Vercel Marketplace and copy its pooled connection string (the one through Neon's connection pooler, not the direct one) into DATABASE_URL. Any Postgres works if you're not on Vercel.

2. Apply migrations (once, after setting DATABASE_URL, and again after pulling any new file under migrations/):

   DATABASE_URL=postgresql://... python -m psx_mcp.db

3. Telegram bot (optional, for alert delivery). Message @BotFather to create a bot and get TELEGRAM_BOT_TOKEN. Send your bot any message, then open https://api.telegram.org/bot<token>/getUpdates to find your numeric TELEGRAM_CHAT_ID. Without these set, alerts still evaluate and land in get_alerts, they just aren't pushed to Telegram.

4. Alert cron. Vercel Hobby's cron only fires once a day, too coarse for intraday alerts, so alerts are checked by POST /api/cron/check-alerts (header X-Cron-Secret: $CRON_SECRET), called every 15 minutes by .github/workflows/check-alerts.yml. Set repo secrets APP_URL (your deployed base URL, no trailing slash) and CRON_SECRET (same value as the server's env var) under Settings → Secrets and variables → Actions, and make sure the workflow is enabled (GitHub disables scheduled workflows on forks/inactive repos — trigger it once manually via Actions → Check PSX alerts → Run workflow if it doesn't seem to be firing). This endpoint works the same way on Render too, so a curl-based cron (e.g. cron-job.org) works there instead of GitHub Actions if you prefer.

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 PSX checks (plus the database/cron ones, if configured) 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

tests/test_extensions.py (watchlist/alerts/insider/corporate/why_moved) needs a real, disposable Postgres -- it's skipped automatically if TEST_DATABASE_URL isn't set:

docker run --rm -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16
TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres pytest -q tests