chowyu12/akshare-mcp

AkShare MCP 服务器 (FastMCP 实现)

这是一个基于 Model Context Protocol (MCP) 的 AkShare 股票数据服务器，使用 FastMCP 库提供简洁高效的股票数据查询和技术分析功能。

功能特性

支持的工具

1. get_stock_basic_info - 获取股票基本信息
2. get_stock_hist_data - 获取股票历史数据
3. get_stock_technical_indicators - 获取股票技术指标
4. get_stock_technical_summary - 获取技术指标分析概要
5. get_stock_realtime_data - 获取股票实时数据
6. get_stock_list - 获取股票列表
7. get_index_data - 获取指数数据

技术指标

• 移动平均线 (MA): MA5, MA10, MA20
• MACD: MACD 线, 信号线, 柱状图
• KDJ: K 值, D 值, J 值
• RSI: 相对强弱指标

安装

1. 安装依赖：

pip install -r requirements.txt

运行方式

使用 Docker（推荐）

# 交互式启动脚本
./docker-start.sh

# 或直接使用 Docker Compose
docker-compose up --build -d

使用便捷启动脚本

./start_server.sh

使用 FastMCP 服务器

./venv/bin/python fastmcp_server.py

其他实现

• SSE 模式: ./venv/bin/python start_sse_server.py
• 原始实现: ./venv/bin/python main.py

测试服务器

使用 FastMCP 测试脚本

python test_fastmcp.py

显示使用帮助

python test_fastmcp.py --help

传统测试方式

python test_server.py

Docker 部署

快速开始

1. 使用交互式脚本（推荐）：

   ./docker-start.sh
   

2. 验证 Docker 配置：

   ./validate-docker.sh
   

环境配置

项目支持多环境部署：

• 开发环境: 包含开发工具和调试功能
• 生产环境: 优化的轻量级镜像

首次运行时会自动创建 .env 文件，可根据需要修改配置。

开发环境部署

# 使用默认配置
docker-compose up --build -d

# 或使用交互式脚本选择开发环境
./docker-start.sh

生产环境部署

# 使用生产配置
docker-compose -f docker-compose.prod.yml up --build -d

# 或使用交互式脚本选择生产环境
./docker-start.sh

常用命令

# 构建镜像
docker build -t akshare-fastmcp .

# 运行容器
docker run -d --name akshare-fastmcp -p 3001:3001 akshare-fastmcp

# 查看容器日志
docker logs -f akshare-fastmcp

# 进入容器
docker exec -it akshare-fastmcp bash

# 查看服务状态
docker-compose ps

# 重启服务
docker-compose restart

# 清理环境
docker-compose down --rmi all --volumes

多阶段构建

Dockerfile 采用多阶段构建：

• builder: 构建阶段，安装依赖
• production: 生产阶段，优化的运行环境
• development: 开发阶段，包含开发工具

环境变量

主要环境变量（参考 env.example）：

• ENVIRONMENT: 运行环境 (development/production)
• PYTHONPATH: Python 路径，默认 /app
• PYTHONUNBUFFERED: 禁用 Python 输出缓冲，默认 1
• HOST: 服务器地址，默认 0.0.0.0
• PORT: 服务端口，默认 3001
• LOG_LEVEL: 日志级别，默认 INFO

数据卷

• ./logs:/app/logs: 日志目录挂载
• ./mcp_config.json:/app/mcp_config.json:ro: 配置文件挂载（只读）
• ./.env:/app/.env:ro: 环境变量文件挂载（只读）

网络配置

• 默认端口: 3001
• 健康检查: 每 30 秒检查一次
• 网络模式: bridge

详细指南

更多 Docker 部署详情请参考：

配置

Claude Desktop 配置 (FastMCP)

在 ~/.config/claude-desktop/claude_desktop_config.json 中添加：

注意: 请将 /path/to/your/project 替换为您的实际项目路径

{
  "mcpServers": {
    "akshare": {
      "command": "/path/to/your/project/venv/bin/python",
      "args": ["/path/to/your/project/fastmcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/your/project"
      }
    }
  }
}

获取项目路径

在项目目录中运行以下命令获取当前路径：

pwd

例如，如果项目位于 /home/user/akshare-mcp，则配置中的路径应为：

• command: /home/user/akshare-mcp/venv/bin/python
• args: ["/home/user/akshare-mcp/fastmcp_server.py"]
• PYTHONPATH: /home/user/akshare-mcp

其他配置选项

SSE 模式配置

注意: 请将 /path/to/your/project 替换为您的实际项目路径

{
  "mcpServers": {
    "akshare": {
      "command": "/path/to/your/project/venv/bin/python",
      "args": ["/path/to/your/project/start_sse_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/your/project"
      },
      "transport": {
        "type": "sse",
        "url": "http://localhost:3001/messages"
      }
    }
  }
}

FastMCP 特点

1. 简洁易用: 使用装饰器语法，代码更简洁
2. 自动类型推断: 基于函数签名自动生成工具模式
3. 内置文档: 自动从函数文档字符串生成工具描述
4. 高性能: 优化的 MCP 协议实现
5. 易于调试: 清晰的错误信息和日志

使用示例

在 Claude 中使用

获取股票600734的基本信息
分析股票600734的技术指标
获取股票600734从20240101到20240320的历史数据
获取上证指数的最新数据

直接调用函数

from fastmcp_server import get_stock_basic_info, get_stock_technical_summary

# 获取基本信息
info = get_stock_basic_info("600734")
print(info)

# 获取技术分析
analysis = get_stock_technical_summary("600734", 14)
print(analysis)

输出格式

所有数据都以 Markdown 表格格式返回，便于阅读和进一步处理。技术分析概要包含：

• 价格趋势分析
• 均线系统判断
• MACD 信号识别
• KDJ 超买超卖判断
• RSI 强弱分析
• 成交量分析

注意事项

1. 股票代码格式: 使用 6 位数字代码（如：600734）
2. 日期格式: YYYYMMDD（如：20240101）
3. 网络连接: 需要网络连接获取股票数据
4. 技术指标: 仅供参考，投资需谨慎
5. 实时数据: 可能有延迟

依赖项

• akshare>=1.12.0
• fastmcp>=0.4.0
• pandas>=1.5.0
• numpy>=1.24.0
• typing-extensions>=4.0.0

文件结构

.
├── fastmcp_server.py       # FastMCP服务器实现（推荐）
├── main.py                 # 原始MCP服务器实现
├── start_sse_server.py     # SSE模式服务器实现
├── test_fastmcp.py         # FastMCP测试脚本
├── test_server.py          # 传统测试脚本
├── requirements.txt        # 依赖项文件
├── mcp_config.json        # MCP配置文件
├── start_server.sh        # 本地启动脚本
├── docker-start.sh        # Docker启动脚本
├── Dockerfile             # Docker镜像构建文件（多阶段）
├── docker-compose.yml     # Docker Compose配置（开发环境）
├── docker-compose.prod.yml # Docker Compose配置（生产环境）
├── .dockerignore          # Docker忽略文件
├── env.example            # 环境变量模板
├── validate-docker.sh     # Docker配置验证脚本
├── DOCKER_GUIDE.md        # Docker部署详细指南
├── venv/                  # 虚拟环境目录
├── logs/                  # 日志目录
└── README.md              # 使用说明

故障排除

常见问题

1. FastMCP 安装失败

   pip install fastmcp>=0.4.0
   

2. 依赖冲突

   # 创建虚拟环境
   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   # 或
   venv\Scripts\activate     # Windows
   
   # 安装依赖
   pip install -r requirements.txt
   

3. 数据获取失败

   • 检查网络连接
   • 确认股票代码正确
   • 检查日期格式

4. 服务器启动失败

   # 检查依赖
   python test_fastmcp.py
   
   # 查看详细错误
   python fastmcp_server.py --debug
   

测试步骤

1. 检查环境

   python test_fastmcp.py
   

2. 启动服务器

   python fastmcp_server.py
   

3. 配置 Claude Desktop

   • 编辑配置文件
   • 重启 Claude Desktop
   • 测试工具调用

版本比较

推荐使用 FastMCP 实现，它提供了最佳的开发体验和性能。

许可证

MIT License