Skip to main content
Glama
Sign In
psx-mcp-server

psx-mcp-server

by ahmedraza-96
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

psx-mcp-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).

Related MCP server: PSX MCP Server

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

Tool

Parameters

Returns

search_symbols

query, sector?, limit=20

Matching tickers (exact matches first). Use first if unsure of a ticker.

get_quote

symbol

Current price, LDCP, OHL, change %, volume, bid/ask, 52-week range, P/E (PKR).

get_intraday

symbol, interval="5min", limit=50

Intraday OHLCV bars (or raw ticks) for the latest session, PKT times.

get_eod_history

symbol, start_date?, end_date?, limit=260

Daily open/close/volume (~5 yrs). Works for indices. No high/low.

get_ohlc_history

symbol, month, year

Full daily OHLCV for one month — the only free source of daily high/low.

get_market_snapshot

category="gainers", limit=15, sector?

Top movers (gainers/losers/volume) plus market breadth.

get_indices

—

All ~18 PSX indices with change %.

get_company_info

symbol

Business description, sector, market cap, shares, free float, P/E.

get_dividends

symbol, limit=10

Payout history (cash/bonus/rights) with book-closure dates.

get_announcements

symbol, limit=10

Recent corporate announcements with document (PDF) links.

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 marketdatarequest@psx.com.pk. Nothing here is investment advice.

License

MIT © Ahmed Raza

Available Tools

10 tools
get_announcementsB

Recent corporate announcements, newest first.

Each item has a date, title, and a link to the PSX document (PDF) when available.

Inputs: symbol (required), limit.

get_company_infoA

Company profile and fundamentals.

Returns business description, sector, market cap (PKR), shares outstanding, free float, and trailing P/E. For the current price use get_quote (this tool omits the live quote to stay focused).

Inputs: symbol (required).

get_dividendsB

Dividend / payout history, newest first.

Details use PSX notation, e.g. '60%(i) (D)' = 60% interim cash dividend, '(B)' = bonus shares, '(R)' = right shares. Includes the book-closure window. Percentages are of face value (PKR 10 for most PSX stocks).

Inputs: symbol (required), limit.

get_eod_historyA

Daily end-of-day history (~5 years), newest first.

Returns open, close and volume per day — this feed has NO high/low; for daily high/low use get_ohlc_history. Works for indices too (e.g. symbol='KSE100'). Dates are ISO (YYYY-MM-DD). ~260 rows is about one trading year. Optionally clip with start_date/end_date (ISO).

Inputs: symbol (required), limit, end_date, start_date.

get_indicesA

All PSX indices (KSE100, KSE30, KMI30, ALLSHR, and ~14 others).

Returns current value, day high/low, change and change % for each. For historical index values call get_eod_history with the index name as the symbol (e.g. 'KSE100').

Inputs: no named parameters.

get_intradayA

Intraday price bars for the current/most recent trading session.

Ticks are aggregated locally into OHLCV bars per interval; 'raw' returns individual ticks (can be thousands — keep limit small). Times are HH:MM in Pakistan Standard Time. Returns the newest limit bars.

Inputs: symbol (required), limit, interval.

get_market_snapshotA

Market-wide snapshot with top movers and a breadth summary.

category: 'gainers' (top change %), 'losers' (bottom change %), or 'volume' (most traded). Optionally filter to a sector (by name). Never returns all ~500 securities; raise limit (max 100) if needed.

Inputs: limit, sector, category.

get_ohlc_historyA

Full daily OHLCV for a single calendar month (has daily high/low).

This is the only free source of daily high/low. Call once per month needed; for a long close-only series prefer get_eod_history (one call). month is 1-12. Prices in PKR.

Inputs: year (required), month (required), symbol (required).

get_quoteA

Get the latest quote for a PSX equity or ETF.

Returns current price, LDCP (last day close), open/high/low, change and change %, volume, bid/ask, 52-week range, and trailing P/E — all in PKR. Live during market hours (Mon-Fri ~09:30-15:30 Pakistan time, UTC+5); outside hours it reflects the last session. For an index use get_indices.

Inputs: symbol (required).

search_symbolsA

Search PSX ticker symbols by symbol or company name.

Use this FIRST whenever you are unsure of the exact ticker (e.g. query='Habib Bank' -> HBL). Optionally filter by exact sector name. Returns matches ranked with exact-symbol hits first.

Inputs: query (required), limit, sector.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: historical data (get_eod_history for close-only, get_ohlc_history for OHLC per month), snapshot for market movers, indices for index data, company info, dividends, announcements, intraday, symbol search, and quote. The descriptions explicitly clarify boundaries (e.g., get_eod_history vs get_ohlc_history, get_indices vs get_quote for indices), reducing ambiguity to near zero.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (get_eod_history, get_ohlc_history, get_market_snapshot, etc.). No deviations or mixed conventions; names are predictable and readable.

    Tool Count5/5

    With 10 tools, the set is well-scoped for a PSX market data server, covering essential operations without redundancy. Each tool serves a distinct data need, and the count is typical for a focused financial API.

    Completeness4/5

    The tool surface covers a wide range: historical data (EOD and OHLC), quotes, indices, company info, dividends, announcements, intraday, and symbol search. However, it lacks tools for news or real-time streaming, and there is no explicit tool for retrieving sector lists or broader market data like commodities, which could be minor gaps for some agents.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • psx-mcp

      revolutionarybukhari
      A
      license
      A
      quality
      D
      maintenance
      MCP server that exposes Pakistan Stock Exchange data (quotes, dividends, announcements, indices) as LLM-callable tools, enabling conversational market queries in plain English.
      9
      5
      MIT

    • PSX MCP Server

      ahad-raza24
      A
      license
      Not graded
      quality
      D
      maintenance
      Provides 12 tools to scrape and access Pakistan Stock Exchange market data, including current prices, historical data, intraday, sector search, and volume analysis.
      6
      MIT

    • PSX MCP

      moiz-imran
      F
      license
      Not graded
      quality
      D
      maintenance
      Enables querying Pakistan Stock Exchange data including market summaries, stock quotes, history, and sector breakdowns using natural language.
      -

    • MCP Stocks Analyzer

      vashishtavarma
      A
      license
      Not graded
      quality
      D
      maintenance
      Provides real-time stock data, news, company fundamentals, and technical indicators for AI assistants via the Model Context Protocol.
      MIT