PSX MCP

psx-mcp

mcp-name: io.github.revolutionarybukhari/psx-mcp

パキスタン証券取引所について、平易な英語で質問できます。

psx-mcp は、PSX の市場データ（株価、配当、発表、指数）を、MCP 対応の AI クライアントが呼び出せるツールとして公開する Model Context Protocol サーバーです。Claude Desktop、Cursor、ChatGPT、自作のエージェントに接続して、次のような質問ができます。

「PSX で配当利回りが 100% を超える、これから支払われる配当は何ですか？」

「配当を受け取るために、今日 MEBL を買うべきですか？」

「OGDC の最近の発表を取得して、重要な内容を要約してください。」

「過去 5 年間の FFC の配当履歴はどうなっていますか？」

LLM が適切なツールを自動的に選び、あなたの言語で回答します。

なぜ MCP なのか？

既存の PSX ツールはライブラリです。インポートして、コードを書き、データを取得します。MCP サーバーは、LLM があなたに代わって呼び出すツールです。英語で質問すると、モデルが get_quote、get_upcoming_dividends、get_dividend_history を呼び出し、回答をまとめます。エンドユーザーが Python を使う必要はありません。

また、これは初めて公開された PSX MCP サーバーです。パキスタン市場向けのエージェント、金融コパイロット、AI 活用型のリサーチワークフローを構築するなら、これを使って市場の状況を把握できます。

公開される機能

ツール（LLM から呼び出し可能）

ツール	機能
get_quote(symbol)	銘柄の現在価格の概要
get_upcoming_dividends(symbol?)	配当予定の一覧。必要に応じて絞り込み、購入期限も算出します
get_buy_deadline(symbol)	配当を受け取るために購入できる最終日（T+2 決済）
get_dividend_history(symbol, years)	過去の配当
get_announcements(symbol?, limit)	最近の企業提出書類と PDF リンク
search_symbols(query)	会社名をあいまい検索してティッカーに変換
get_indices()	KSE100、KSE30、KMI30、ALLSHR、PSXDIV20 など
get_market_status()	現在 PSX が開いているか、次にいつ開くか
screen_dividend_stocks(min_payout_pct)	配当額で今後の配当を絞り込み

リソース（読み取り専用コンテキスト）

• psx://market-status
• psx://indices
• psx://upcoming-dividends

プロンプト（テンプレート化されたワークフロー）

• analyze_dividend_play(symbol) — 配当取引の詳細分析
• portfolio_review(symbols) — 保有銘柄リストのレビュー
• find_dividend_opportunities(min_payout_pct) — スクリーナーと銘柄ごとの分析

インストール

Python 3.10 以降が必要です。

# From PyPI (once published)
pip install psx-mcp

# Or with uv (recommended)
uv tool install psx-mcp

# From source
git clone https://github.com/revolutionarybukhari/psx-mcp
cd psx-mcp
pip install -e .

Claude Desktop に接続する

Claude Desktop の設定ファイルを編集します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "psx": {
      "command": "uvx",
      "args": ["psx-mcp"]
    }
  }
}

Claude Desktop を再起動します。接続アイコンに PSX ツールが表示されます。次のように試してみてください。

「今週、PSX で予定されている配当は何ですか？」

Cursor に接続する

設定 → MCP → サーバーを追加：

{
  "mcpServers": {
    "psx": {
      "command": "psx-mcp",
      "args": []
    }
  }
}

リモート HTTP サーバーとして実行する

共有利用、チーム利用、またはホストされたエージェント向けです。

psx-mcp --transport http --host 0.0.0.0 --port 8000

サーバーは http://localhost:8000/mcp でアクセスできます。MCP Inspector でテストできます。

npx @modelcontextprotocol/inspector
# point it at http://localhost:8000/mcp

試してみるプロンプトの例

接続したら、次のように試してみてください。

"List all PSX stocks paying more than 50% dividend right now,
sorted by buy deadline."

"For each stock in my portfolio (HBL, OGDC, PSO, ENGRO, MEBL),
tell me if there's an upcoming dividend and what the buy deadline is."

"Find me consistent dividend payers on PSX — companies that have
paid every year for the last 3+ years with payouts above 30%."

"What's happening with FFC today? Pull the quote and the latest
3 announcements."

"Walk me through the dividend trade for MARI step by step."

仕組み

   ┌──────────────────────┐         ┌─────────────────┐
   │  Claude / Cursor /   │  MCP    │   psx-mcp       │
   │  ChatGPT / Agent     │ ──────► │   server        │
   └──────────────────────┘         └────────┬────────┘
                                             │ httpx + bs4
                                             ▼
                                    ┌─────────────────┐
                                    │ dps.psx.com.pk  │
                                    └─────────────────┘

ツールは公開されている PSX Data Portal にアクセスし、BeautifulSoup で HTML を解析して、構造化 JSON に正規化してから LLM に返します。キーも認証も不要で、利用者がスクレイピングに悩まされることもありません。

アーキテクチャに関するメモ

• すべて非同期です。 すべてのスクレイパー関数で httpx.AsyncClient を使用するため、MCP の呼び出しがブロックされません。
• 銘柄シンボルのキャッシュ。 search_symbols を高速化するため、PSX の銘柄シンボル一覧全体を24時間キャッシュします。
• 取引日の計算。 買付期限の計算では、週末と dividend_calc.PSX_HOLIDAYS_2026 に設定した祝日を除外し、BC_From − 2 trading days を使用します。
• 永続化なし。 このサーバーはステートレスです。アラートやウォッチリストなどの状態は、クライアント側で管理してください。

相性のよいツール

このサーバーは、より広範な PSX オープンソースツールキットの一部です。

• psx-dividend-alert — 近日予定されている配当に関する Telegram のプロアクティブなアラート
• psx-cgt-calculator — FIFO ロット方式によるパキスタンのキャピタルゲイン税の計算
• psx-zakat-calculator — 株式保有分に対するザカートの計算（ザカート対象資産方式）
• psx-broker-statement-parser — KTrade／AKD／JS Global の PDF を正規化
• psx-announcements-summarizer — PSX のすべての提出書類を LLM で要約

MCP サーバーにより、これらすべてを LLM から呼び出せます。組み合わせれば、PSX リサーチのための完全な対話型スタックを構築できます。

制限事項／率直な注意点

• PSX のデータには約5分の遅延があります。 公開データポータルと同様です。
• スクレイピングは不安定です。 PSX が HTML を変更すると、パーサーの更新が必要になります。プルリクエストを歓迎します。
• 注文の発注には対応していません。 このサーバーは読み取り専用です。設計上、取引を実行する経路はありません。
• 祝日リストは仮のものです。 PSX が年間カレンダーを公開したら、dividend_calc.py の PSX_HOLIDAYS_2026 を編集してください。未設定の場合も、買付期限の計算では週末は正しく除外されますが、イードや独立記念日の週はずれが生じます。
• 個人利用向けです。 PSX の利用規約では、ライセンスなしでの市場データの商用再配布が制限されています。ライセンスが必要な場合は、[email protected] までメールでお問い合わせください。

コントリビューション

• ツールを追加するには、scraper.py に関数を記述し、server.py で @mcp.tool() を使って公開して、docstring を追加してください（docstring は LLM に表示されるツールの説明になるため、明確に記述してください）。
• テストを追加するには、tests/ に非同期テストを配置してください。MCP SDK はインメモリテストに対応しています。
• HTML パーサーが動作しなくなった場合は、問題の URL と該当箇所を含むスニペットを添えて、Issue を作成してください。

ライセンス

MIT。詳しくは LICENSE をご覧ください。