PSX MCP

psx-mcp

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

用通俗英语对话巴基斯坦证券交易所。

psx-mcp 是一个 Model Context Protocol 服务，将 PSX 市场数据（报价、股息、公告、指数）封装为工具，供任何兼容 MCP 的 AI 客户端调用。将其连接到 Claude Desktop、Cursor、ChatGPT 或你自己的 Agent，然后提出这样的问题：

“PSX 上有哪些即将派发的股息，派息率超过 100%？”

“我今天应该买入 MEBL 来领取股息吗？”

“调取 OGDC 最近的公告，并总结其中的重要内容。”

“过去 5 年 FFC 的股息记录如何？”

大模型会自动选择合适的工具，并用你的语言作答。

为什么选择 MCP？

现有的 PSX 工具都是库——你导入它们、编写代码、获取数据。MCP 服务则是由大模型代表你调用的工具。你用英语提问，模型调用 get_quote、get_upcoming_dividends、get_dividend_history，并综合生成答案。最终用户无需使用 Python。

这也是首个发布的 PSX MCP 服务。如果你正在为巴基斯坦市场构建 Agent、金融副驾或 AI 增强型研究工作流，它能为它们提供洞察。

提供的功能

工具（可由大模型调用）

工具	功能
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 服务运行

适用于共享、团队使用或托管 Agent：

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，然后返回给大模型。无需密钥、无需身份验证，使用者也不必为数据抓取问题烦恼。

架构说明

• 全程异步。 所有抓取函数都使用 httpx.AsyncClient，因此 MCP 调用不会阻塞。
• 符号缓存。 完整的 PSX 符号列表会缓存 24h，以加快 search_symbols 的速度。
• 交易日计算。 买入截止日期按 BC_From − 2 个交易日 计算，并跳过周末以及 dividend_calc.PSX_HOLIDAYS_2026 中配置的节假日。
• 不持久化。 此服务是无状态的。状态（提醒、观察列表）由你的客户端管理。

适合搭配使用

这是更广泛的 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 申报文件摘要

MCP 服务让这些工具都能由大模型调用。将它们搭配使用，即可构建完整的对话式 PSX 研究工具栈。

局限性 / 说明

• PSX 数据延迟约 5 分钟。 与公开数据门户相同。
• 网页抓取容易失效。 如果 PSX 更改 HTML，就需要更新解析器。欢迎提交 PR。
• 不支持下单。 这是只读服务。此处没有任何发送交易指令的途径——这是有意为之。
• 节假日列表尚未完善。 PSX 发布年度日历后，请编辑 dividend_calc.py 中的 PSX_HOLIDAYS_2026。如果不编辑，该计算会正确跳过周末，但在开斋节／独立日所在周会有偏差。
• 仅供个人使用。 PSX 条款限制未经许可商业性再分发市场数据。如需许可，请发送邮件至 [email protected]。

贡献

• 添加工具：在 scraper.py 中编写函数，在 server.py 中使用 @mcp.tool() 将其公开，并添加文档字符串（文档字符串会成为大模型的工具描述，请写清楚）。
• 添加测试：在 tests/ 中添加异步测试。MCP SDK 支持内存测试。
• 如果 HTML 解析器出现故障，请提交问题，并附上导致问题的 URL 和相关代码片段。

许可证

MIT。请参阅 LICENSE。