PSX MCP Server

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

🎥 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

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

1. Build the Docker image:

docker build -t psx-mcp-server .

2. Run the container:

docker run -it psx-mcp-server

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

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

Development

Available Commands

make help          # Show all available commands