PSX MCP Server (Modified for Remote/Cloud Deployment)

Based on PSX-MCP-Server by Ahad Raza, modified with HTTP transport, API key authentication, and cloud deployment support. See LICENSE for the original MIT license.

A Model Context Protocol (MCP) server that provides tools to scrape and access Pakistan Stock Exchange (PSX) market data.

What's Changed From the Original

This fork modifies the original stdio-only local server to also run as a remotely-hosted HTTP service, so it can be deployed to a cloud platform and connected to Claude (or any other MCP client) from anywhere, not just from a process running on the same machine.

File	Change
src/psx_mcp/server.py	Added an ApiKeyMiddleware class that checks every incoming MCP request for a valid X-API-Key header (read from the PSX_MCP_API_KEY environment variable). Added an unauthenticated /health route for hosting-provider uptime checks. Added a streamable-http transport branch to the __main__ block.
scripts/start_server.py	Bug fix: this script had its own separate mcp.run() call with no transport arguments, which was silently overriding the HTTP transport settings added in server.py and defaulting back to stdio. Fixed to read PORT from the environment and launch with transport="streamable-http", host="0.0.0.0".
requirements.txt	Added starlette>=0.37.0 explicitly, since server.py now imports it directly for the /health route (previously only pulled in indirectly via fastmcp).
Dockerfile	Changed exposed port from 3000 to 8080/dynamic PORT to match cloud platform conventions (Render, Cloud Run, etc. inject their own PORT value at runtime).
LICENSE	Added — the original repo declared MIT in pyproject.toml but did not include the license file itself.

All 12 original tools (market_data, intraday, history, sector, gainers, losers, date_range, time_range, ohlcv, multi_ohlcv, price_at_time, volume_analysis) are unchanged and work identically to the original — only the transport layer and authentication were added.

Running remotely vs. locally

• Original / local use (stdio): still works exactly as documented below, for use with a local MCP client like Gemini CLI or Claude Desktop's local config.
• New / remote use (HTTP): set PSX_MCP_API_KEY and optionally PORT, then run python scripts/start_server.py — the server now listens on http://0.0.0.0:$PORT/mcp and requires the X-API-Key header on every request. This is what allows deployment to Render, Cloud Run, or any other container host.

---

🎥 Demo Video

Watch this demo to see the PSX MCP Server in action with real-time market data!

Features

This MCP server provides 12 powerful tools for comprehensive PSX data access:

📊 Basic Tools (Simple & Intuitive)

1. market_data() - Get current market data for all 460+ stocks listed on PSX
2. intraday(symbol) - Get intraday time series data for a specific stock
3. history(symbol) - Get end-of-day historical data for a specific stock (past 5 years)
4. sector(sector) - Search stocks by sector
5. gainers(limit) - Get top gaining stocks
6. losers(limit) - Get top losing stocks

🎯 Advanced Tools (Clean & Powerful)

7. date_range(symbol, start, end) - Get EOD data for specific date range (YYYY-MM-DD format)
8. time_range(symbol, start, end) - Get intraday data for specific time range (YYYY-MM-DD HH:MM:SS format)
9. ohlcv(symbol) - Get OHLCV (Open, High, Low, Close, Volume) data for specific stock
10. multi_ohlcv(symbols) - Get OHLCV data for multiple stocks (comma-separated symbols)
11. price_at_time(symbol, timestamp) - Get closest price data at specific Unix timestamp
12. volume_analysis(symbol, days) - Analyze volume patterns over specified number of days

Installation

Option 1: Direct Installation (local, stdio)

1. Install dependencies:

pip install -r requirements.txt

2. Configure Gemini CLI (copy and customize the template):

cp gemini_config.template.json gemini_config.json
# Edit gemini_config.json with your project path

3. Run the MCP server:

python scripts/start_server.py

Option 2: Development Installation

1. Install with development tools:

make setup
# or
pip install -e ".[dev]"

2. Run with Makefile:

make run-server

Option 3: Docker (local or cloud deployment)

1. Build the Docker image:

docker build -t psx-mcp-server .

2. Run the container (requires PSX_MCP_API_KEY to be set — see below):

docker run -p 8000:8000 -e PSX_MCP_API_KEY=your-key-here -e PORT=8000 psx-mcp-server

Option 4: Remote HTTP mode (new)

Set the required environment variable and run directly:

export PSX_MCP_API_KEY=your-long-random-key-here
export PORT=8000   # optional, defaults to 8000
python scripts/start_server.py

The server will be reachable at http://localhost:8000/mcp (or your deployed URL) and requires the X-API-Key header on every MCP request. An unauthenticated health check is available at /health.

Configuration

Template Files

The project includes template configuration files for easy setup:

• gemini_config.template.json - Simple Gemini CLI configuration template
• mcp_config.template.json - Advanced MCP configuration template with additional settings

Quick Setup (local stdio)

1. Copy the template file:

cp gemini_config.template.json gemini_config.json

2. Edit the configuration with your project path:

{
  "mcpServers": {
    "psx-scraper": {
      "command": "python",
      "args": ["/your/actual/path/scripts/start_server.py"],
      "env": {
        "PYTHONPATH": "/your/actual/path/src"
      }
    }
  }
}

3. Connect Gemini CLI:

gemini --config gemini_config.json

Environment Variables (remote/HTTP mode)

Variable	Required	Description
PSX_MCP_API_KEY	Yes, for HTTP mode	Shared secret required in the X-API-Key header on every MCP request. Set this as a secret in your hosting provider's dashboard — never commit it to the repo.
PORT	No	Port to bind to. Most hosting platforms (Render, Cloud Run) set this automatically. Defaults to 8000.

Development

Available Commands

make help          # Show all available commands
make test          # Run test suite
make lint          # Run linting checks
make format        # Format code with black
make run-demo      # Run demonstrations
make clean         # Clean build artifacts

Data Sources

The server scrapes data from the following PSX endpoints:

• https://dps.psx.com.pk/market-watch - Market watch data
• https://dps.psx.com.pk/timeseries/int/{SYMBOL} - Intraday data
• https://dps.psx.com.pk/timeseries/eod/{SYMBOL} - End-of-day data

Usage

The server can be used with any MCP client, such as Gemini CLI, Claude Desktop, or claude.ai (via a custom connector, in HTTP mode). The tools return JSON data that can be processed by the client.

Example Queries

Basic Data (Super Simple):

• "Show me market data" → market_data()
• "Get HBL intraday data" → intraday('HBL')
• "Show HBL history" → history('HBL')
• "Find banking stocks" → sector('Banking')
• "Top 5 gainers" → gainers(5)

Advanced Filtering (Clean & Intuitive):

• "HBL data from Jan to Feb" → date_range('HBL', '2024-01-01', '2024-02-01')
• "HBL intraday 9AM to 3PM" → time_range('HBL', '2024-10-04 09:00:00', '2024-10-04 15:00:00')
• "HBL OHLCV data" → ohlcv('HBL')
• "OHLCV for HBL,OGDC" → multi_ohlcv('HBL,OGDC')
• "HBL volume analysis" → volume_analysis('HBL', 30)

Example Stock Symbols

• HBL - Habib Bank Limited
• OGDC - Oil and Gas Development Company
• PTC - Pakistan Telecommunication Company
• LUCK - Lucky Cement
• ENGRO - Engro Corporation

Data Models

Stock Data

• Symbol, Sector, Listed In
• LDCP, Open, High, Low, Current prices
• Change amount and percentage
• Volume traded

Time Series Data

• Unix timestamp
• Price/Close price
• Volume
• Open price (for EOD data)

Error Handling

All tools include proper error handling and return error messages in JSON format if requests fail.

Notes on Data Reliability

This server scrapes PSX's public website (dps.psx.com.pk) directly — it is not an official PSX API. It provides price/volume/OHLCV data only, not fundamentals (EPS, profit, dividends, corporate actions). Verify any figure that will inform an actual trading decision against PSX's primary filings before acting on it.