Skip to main content
Glama
psxdata-mcp

psxdata-mcp

by psxdata

psxdata-mcp

An MCP server that gives AI assistants Pakistan Stock Exchange data. It runs locally in Docker: the assistant loads PSX data (prices, screener, index constituents, sectors, filings, debt market, margin-eligible scrips) into a private in-memory DuckDB and answers your questions with SQL. It's built on psxdata.

Requires: Docker, except for the Claude Desktop one-click bundle (see below), which needs uv instead.

Install

Install in VS Code

Claude Code (plugin, recommended):

claude plugin marketplace add psxdata/psxdata-mcp
claude plugin install psxdata@psxdata-mcp

Claude Code (plugin, hosted server: invite-only, no Docker, adds warehouse marts):

claude plugin marketplace add psxdata/psxdata-mcp
claude plugin install psxdata-hosted@psxdata-mcp

Claude Code asks for the server URL when the plugin is enabled; use the one from your invitation. Then run /mcp and sign in to psxdata. Install one of the two plugins, not both.

Claude Code (server only):

claude mcp add --transport stdio --scope user psxdata -- docker run -i --rm -v psxdata-cache:/home/app/.psxdata mtauha/psxdata-mcp:latest

Cursor: open this link: cursor://anysphere.cursor-deeplink/mcp/install?name=psxdata&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItaSIsIi0tcm0iLCItdiIsInBzeGRhdGEtY2FjaGU6L2hvbWUvYXBwLy5wc3hkYXRhIiwibXRhdWhhL3BzeGRhdGEtbWNwOmxhdGVzdCJdfQ==

Claude Desktop (one-click): download psxdata-mcp-<version>.mcpb from the latest release and open it (or drag it into Settings → Extensions). This route needs no Docker, but it runs on uv, which it uses to fetch Python and the dependencies on first launch; install uv first if Claude Desktop reports it missing. The first launch takes a few seconds longer than later ones.

Any other client: add to its MCP config (Claude Desktop's is claude_desktop_config.json):

{
  "mcpServers": {
    "psxdata": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "psxdata-cache:/home/app/.psxdata", "mtauha/psxdata-mcp:latest"]
    }
  }
}

Related MCP server: psx-mcp

Tools

Tool

What it does

load_prices(symbols, start?, end?)

Daily OHLCV for up to 50 symbols → prices

load_screener()

All ~729 symbols with price, P/E, dividend yield, market cap → screener

load_index(name)

Constituents and weights of KSE100, KSE30, KMI30, … → index_constituents

load_sectors()

37-sector summary → sectors

load_fundamentals(symbols?)

Filed financial reports list → fundamentals

load_symbols()

All listed symbols with name and sector → symbols

load_debt_market()

TFCs, Sukuks, government securities → debt_market

load_eligible_scrips()

Margin-eligible scrips by market → eligible_scrips

query(sql)

DuckDB SQL over loaded tables (≤200 rows, 30 s, no file/network access)

list_tables()

What's loaded, row counts, load time

quote(symbol)

Latest snapshot for one symbol

Ask things like "How has OGDC done against KSE-100 constituents this year?" or "Which cement stocks have a P/E under 6?"

Skills

Ready-made analysis workflows, served as MCP prompts (pick them from your client's prompt menu, e.g. /mcp__psxdata__tearsheet in Claude Code) and shipped as skills in the Claude Code plugin, which Claude loads on its own when a request matches.

Skill

What it does

psx-playbook

The rules every analysis follows: data traps, SQL patterns, web cross-checks

tearsheet(symbol)

One-page report on a stock: performance, risk, valuation vs. sector, filings, news

screen(criteria?)

Value, dividend or momentum presets, or your own conditions, with red flags

shariah-screen(screen?)

The same screens limited to KMI All-Share members, with purification notes

compare(symbols, period?)

2–10 stocks side by side: returns, risk, correlation, valuation, price path

market-wrap(period?)

Daily or weekly summary: KSE-100 drivers, breadth, sectors, movers, news

Sources live in src/psxdata_mcp/skills/*.md; skills/ is generated from them with uv run python scripts/sync_skills.py (a test fails if the two drift).

Good to know

  • Prices are PKR and not adjusted for splits, bonus issues or dividends.

  • Historical data is cached in the psxdata-cache Docker volume, so each symbol is downloaded once. Live data (screener, sectors, quotes) refreshes every 15 minutes.

  • Loaded tables live in memory and reset when the assistant session ends.

  • Data is scraped from the public PSX website; it isn't an official feed.

Development

uv sync
uv run pytest                    # unit + server tests
uv run pytest -m live            # hits real PSX
docker build -t psxdata-mcp:dev . && uv run pytest -m container
uv run python scripts/stage_mcpb.py build/mcpb      # stage the Claude Desktop bundle
npx @anthropic-ai/mcpb pack build/mcpb build/psxdata-mcp.mcpb
PSXDATA_MCP_BUNDLE=build/psxdata-mcp.mcpb uv run pytest -m bundle
npx @modelcontextprotocol/inspector docker run -i --rm psxdata-mcp:dev

License

MIT

Available Tools

11 tools
list_tablesA

List loaded tables with row counts and load time (UTC). No columns — use query("DESCRIBE ") for those.

Inputs: no named parameters. Returns: result

load_debt_marketB

Load PSX debt instruments (TFCs, Sukuks, government securities: face value, dates, coupon rate, maturity) into table debt_market, one category per instrument group.

Inputs: no named parameters. Returns: result

load_eligible_scripsB

Load margin-trading eligible scrips by market category into table eligible_scrips.

Inputs: no named parameters. Returns: result

load_fundamentalsA

Load the list of filed financial reports (year, type, period, posting date, document link) into table fundamentals. Not valuation metrics — those are in screener. Omit symbols to load all filings.

Inputs: symbols. Returns: result

load_indexA

Load constituents and weights of a PSX index (e.g. KSE100, KSE30, KMI30), including each constituent's ex_flag, into table index_constituents. Re-loading an index replaces only that index's rows.

Inputs: name (required). Returns: result

load_pricesA

Load daily OHLCV prices (PKR, unadjusted) for up to 50 PSX symbols into table prices.

Omit start/end for the full history. Re-loading a symbol replaces all its rows.

Inputs: symbols (required), end, start. Returns: result

load_screenerA

Load the full PSX screener (~750 symbols: sector, price, market cap, P/E, dividend yield, free float, 30-day avg volume, 1-year change, traded_today, ex_flag) into table screener. 15-min snapshot. See traded_today and ex_flag in the server instructions — filter on them before ranking daily moves.

Inputs: no named parameters. Returns: result

load_sectorsA

Load the PSX sector summary (advances, declines, turnover, market cap for all 37 sectors) into table sectors. 15-min snapshot.

Inputs: no named parameters. Returns: result

load_symbolsB

Load all listed PSX symbols with company name, sector and ETF/debt/GEM flags into table symbols.

Inputs: no named parameters. Returns: result

queryA

Run DuckDB SQL over the loaded tables. Returns at most 200 rows as a table; aggregate or LIMIT for large results. You may create views/tables. No file or network access.

Inputs: sql (required). Returns: result

quoteA

Get the latest snapshot for one PSX symbol (price, sector, market cap, P/E, dividend yield, 1-year change). Does not create a table.

Inputs: symbol (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation4/5

    Each load_* tool targets a distinct PSX dataset and writes to its own named table, so boundaries are mostly clear. The main risk is overlap between load_screener, load_symbols, and quote (all carry price/sector/market-cap-ish fields), but the descriptions explicitly differentiate them (snapshot valuation table vs. reference list vs. single-symbol live quote).

    Naming Consistency4/5

    Eight of eleven tools follow a clean load_<dataset> pattern, and the remaining query/quote/list_tables are short, readable verbs. list_tables is the only verb that deviates from the load_ prefix, but that's semantically appropriate since it inspects state rather than loading data.

    Tool Count5/5

    Eleven tools sit comfortably in the ideal range, with each loader covering a genuinely different PSX data domain (screener, index, debt, prices, sectors, fundamentals, etc.). The generic query tool absorbs ad-hoc analysis so no extra specialized tools are needed.

    Completeness4/5

    The surface covers the full load-then-query workflow: market snapshots, indices, prices, sectors, debt, fundamentals, and a SQL escape hatch, with no dead ends for typical analysis. Minor gaps exist — no tool for intraday data, company news/announcements, or retrieving actual financial statement contents beyond the filing index — but query and reload semantics let agents work around most of them.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      F
      maintenance
      Enables AI assistants and IDEs to execute SQL queries on local DuckDB databases, in-memory databases, or cloud-stored databases with support for flexible connections and configurable result limits.
      1
      1
      MIT
    • 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
      30 PyPI
      5
      MIT
    • 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.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude to fetch live Pakistan Stock Exchange data from the PSX Data Portal, including quotes, market summaries, top movers, fundamentals, price history with indicators, dividends, announcements, index constituents, sectors, and portfolio valuation. It also supports screening and comparing listed stocks by valuation, technical, sector, index, and Shariah criteria.
      MIT