hstock-mcp 0.2.0

A Flask server to provide A-share market data via MCP.

MCP行情服务器 (PyPI & uvx/JSON 安装) - 安装与使用指南

1. 概述

本项目提供了一个基于Flask的A股行情数据服务器，旨在通过MCP (模型上下文协议) 提供服务。您可以将此服务器通过PyPI发布，并使用uvx命令或JSON配置在MCP客户端（如Cursor, Cherry Studio）中自动安装和运行。

主要功能包括：

• 获取A股指定标的（指数、个股、ETF等）的历史行情数据（日/周/月频）。
• 获取上海证券交易所最新的股票数据总貌。
• 提供深圳证券交易所行业成交数据的接口（目前为占位符，具体功能待进一步实现）。

2. 先决条件

• Python 3.11 或更高版本
• uv: 一个快速的Python包安装器和解析器。如果尚未安装，请参照其官方文档安装 (通常 pip install uv)。

3. 安装与运行 (通过 uvx)

一旦该包发布到PyPI (包名为 hstock-mcp)，您可以使用 uvx 直接运行它。uvx 会自动处理包的下载、安装到临时环境和执行。

# 假设包已发布到PyPI
uvx hstock-mcp --host <your_desired_host> --port <your_desired_port>

例如，要在本地 127.0.0.1 的 8888 端口启动服务器：

uvx hstock-mcp --host 127.0.0.1 --port 8888

服务器启动后，您会看到类似以下的输出：

Starting MCP Server on http://127.0.0.1:8888
 * Serving Flask app 'mcp_server_lib.app'
 * Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:8888
Press CTRL+C to quit

命令行参数说明 (由 hstock-mcp 提供):

• --host <ip_address>: 服务器监听的主机地址 (默认为 127.0.0.1)。使用 0.0.0.0 可以让服务器从网络中的其他计算机访问。
• --port <port_number>: 服务器监听的端口号 (默认为 5000)。
• --debug: 启用Flask的调试模式 (默认为关闭)。

4. MCP客户端JSON配置示例

对于支持JSON配置的MCP客户端，您可以使用类似以下的配置来集成此服务器：

{
  "mcpServers": {
    "my_ashare_market_data": {  // 您可以自定义此键名
      "command": "uvx",
      "args": [
        "hstock-mcp", // PyPI上的包名
        "--host", "0.0.0.0",   // 示例：监听所有接口
        "--port", "8889"      // 示例：使用8889端口
        // 您可以根据需要添加其他命令行参数，如 --debug
      ],
      "env": {},
      "disabled": false
    }
  }
}

说明:

• "command": "uvx": 指定使用 uvx 来执行。
• "args": ["hstock-mcp", ...] : 第一个参数是PyPI上的包名，后续参数是传递给服务器启动脚本的命令行参数。

5. API接口简述

服务器启动后，可以通过HTTP GET请求访问以下端点：

• /mcp/marketdata/history：获取A股历史行情数据。

  • 参数: symbol, frequency, start_date (可选), end_date (可选)
  • 示例: curl "http://127.0.0.1:8889/mcp/marketdata/history?symbol=000001.SZ&frequency=daily&start_date=2024-04-01&end_date=2024-04-30" (假设服务器运行在8889端口)

• /mcp/marketdata/sse/overview：获取上海证券交易所股票数据总貌。

  • 示例: curl "http://127.0.0.1:8889/mcp/marketdata/sse/overview"
  • 注意：此接口的部分数据字段可能因上游数据源问题返回空值。

• /mcp/marketdata/szse/industry_transactions：获取深圳证券交易所行业成交数据 (当前为占位符，返回501错误)。

  • 参数: symbol, date
  • 示例: curl "http://127.0.0.1:8889/mcp/marketdata/szse/industry_transactions?symbol=000001&date=20231231"

详细的API设计文档 (api_design_*.md) 之前已提供，可供参考。

6. 项目文件结构 (用于PyPI发布)

hstock-mcp/
├── mcp_server_lib/           # 主要的Python包代码
│   ├── __init__.py
│   ├── app.py                # Flask应用定义和API路由
│   ├── akshare_provider.py   # AKShare数据源接口实现
│   ├── yahoo_finance_provider.py # Yahoo Finance数据源接口实现
│   └── cli.py                # 命令行入口脚本
├── pyproject.toml            # uv 和 setuptools 构建配置文件
├── requirements.txt          # 依赖列表 (主要供参考，uv使用pyproject.toml)
└── README.md                 # (本文件) 安装与使用指南

7. 故障排除与已知问题

• uvx 执行问题: 确保 uv 已正确安装并配置在系统PATH中。网络连接必须可用以下载PyPI包。
• 上交所数据总貌字段为空: 部分数据字段可能返回null，这可能源于AKShare上游数据的问题。
• 深交所行业成交数据未实现: 此功能当前返回501错误，待后续找到合适的数据源后实现。

如果您在安装或使用过程中遇到任何问题，请检查Python环境、uv安装以及依赖项是否正确安装。