FinSage 🚀

给 AI Agent 装上「A 股眼睛」——一个专注 A 股的金融分析 MCP Server。用自然语言分析个股、按条件选股、生成公司简报；数据默认离线 mock，填入 key 即接真实 A 股与 LLM。

🔗 Live Demo：https://a7c068bdc039499baa6defa9a85d7cce.gz3.agentos-app.net （交互式体验四个核心能力，默认展示离线演示数据）

FinSage 把「大语言模型的理解能力」与「金融数据」桥接起来：你（或你的 AI Agent）用中文提问，它先让 LLM 解析意图与参数，再调用数据层拉取行情/财务，最后由 LLM 合成可读的分析结论。既可作为 MCP Server 被任意支持 MCP 的客户端（Claude Desktop、Cursor、各类 Agent 框架）调用，也可作为 REST API 独立部署。

差异化定位：专注 A 股 + 免费数据源（akshare）+ 可插拔 LLM。大多数开源金融 AI 工具盯着美股，A 股场景明显供给不足——这是天然的护城河；而 MCP 形态让它刚好卡在 2026 年「Agent / 工具调用」的流量入口上。

✨ 特性

🤝 MCP 原生：四个核心 tools + 一个组合工具直接接入任意 MCP 客户端，让你的 Agent 能「查 A 股、做分析、做对比、出研报」
🔗 组合工具 research_company：一句话完成「分析 + 简报 + 同业对比」，专为 Agent 编排设计，无需多次往返
🌐 Remote MCP：默认 stdio（本地），设 FINSAGE_MCP_TRANSPORT=sse 即可云端暴露，被远程 Agent 通过 MCP 协议调用
🗣️ 自然语言接口：分析贵州茅台的毛利率和ROE、筛选低估值高ROE的股票
🧩 双层可插拔架构：数据层（mock / akshare）、LLM 层（mock / OpenAI 兼容）
📴 零依赖即可跑通：默认 mock 模式离线可用，无需 API key、无需联网
🐳 一键部署：Docker / docker-compose 就绪，附带 GitHub Actions CI
📚 自带 OpenAPI 文档：REST 模式启动后访问 /docs

🏗️ 架构

flowchart LR
    C[MCP 客户端\nClaude/Cursor/Agent] -->|自然语言| MCP[FinSage MCP Server]
    API[FastAPI /api/v1] -->|自然语言| SVC[编排层 services]
    MCP --> SVC
    SVC --> LLM[LLM 层\n解析意图+合成]
    SVC --> DATA[数据层\n行情/财务]
    LLM -. mock / OpenAI兼容 .-> LLMIMPL[(LLMProvider)]
    DATA -. mock / akshare .-> DATAIMPL[(DataProvider)]
    SVC --> RESP[结构化 JSON 响应]

两种入口共享同一套编排与数据/LLM 层：

入口	能力
MCP tools	`analyze_stock` / `screen_stocks` / `stock_report` / `compare_stocks` / `research_company`
REST API	`POST /api/v1/analyze` / `/screen` / `/report` / `/compare` / `/research` + `GET /health`

🚀 快速开始

1. MCP 模式（推荐，零配置）

pip install -r requirements.txt
python -m finsage            # 或: finsage-mcp

默认以 stdio 方式启动 MCP Server。把它接入支持 MCP 的客户端即可。

远程传输（Remote MCP）：若要让云端部署的 FinSage 被远程 Agent 通过 MCP 协议调用，设置环境变量以 SSE 模式启动：

FINSAGE_MCP_TRANSPORT=sse python -m finsage

SSE 端点默认监听 127.0.0.1:8000（可用 FASTMCP_SERVER_HOST / FASTMCP_SERVER_PORT 调整）。远程客户端（或网关）即可用 MCP-over-SSE 连上来——这正是「给任意 Agent 装 A 股眼睛」的云端形态。

Claude Desktop 配置（claude_desktop_config.json）：

{
  "mcpServers": {
    "finsage": {
      "command": "python",
      "args": ["-m", "finsage"],
      "env": {
        "FINSAGE_DATA_PROVIDER": "mock",
        "FINSAGE_LLM_PROVIDER": "mock"
      }
    }
  }
}

本地调试（MCP Inspector）：

npx @modelcontextprotocol/inspector python -m finsage

2. REST API 模式

pip install -r requirements.txt
uvicorn finsage.main:app --reload --port 8000
# 打开 http://localhost:8000/docs

3. Docker

docker compose up --build

4. 真实模式（A 股数据 + 真实 LLM）

pip install ".[real]"        # 安装 akshare + openai
cp .env.example .env
# 编辑 .env:
#   FINSAGE_DATA_PROVIDER=akshare
#   FINSAGE_LLM_PROVIDER=openai
#   FINSAGE_LLM_API_KEY=sk-xxx
python -m finsage            # 或 uvicorn finsage.main:app --port 8000

支持任意 OpenAI 兼容端点（如 DeepSeek）：把 FINSAGE_LLM_BASE_URL 改成对应地址即可。

📡 调用示例

MCP（任意客户端中自然语言即可）：

用户: 分析贵州茅台的毛利率和ROE
→ analyze_stock(query="分析贵州茅台的毛利率和ROE", symbol="600519")

用户: 筛选低估值高ROE的白酒股
→ screen_stocks(query="低估值高ROE的白酒股", top_n=10)

用户: 给我 600519 的公司简报
→ stock_report(symbol="600519", include_risk=true)

用户: 对比贵州茅台和五粮液
→ compare_stocks(symbols=["600519","000858"])

用户: 给我一份贵州茅台的综合研究，顺便和五粮液比一下
→ research_company(symbol="600519", compare_with=["000858"])

REST：

# 综合研究（分析 + 简报 + 同业对比，一步到位）
curl -X POST http://localhost:8000/api/v1/research \
  -H 'Content-Type: application/json' \
  -d '{"symbol":"600519","compare_with":["000858"]}'

REST：

curl -X POST http://localhost:8000/api/v1/analyze \
  -H 'Content-Type: application/json' \
  -d '{"query":"分析贵州茅台的毛利率和ROE","symbol":"600519"}'

# 对比多标的
curl -X POST http://localhost:8000/api/v1/compare \
  -H 'Content-Type: application/json' \
  -d '{"symbols":["600519","000858"]}'

🖥️ 交互式演示页

仓库内含一个零依赖的静态演示页 demo/index.html，可直接体验四个核心能力（个股分析 / 条件选股 / 公司简报 / 多标的对比），对比页带 Chart.js 图表。

在线体验：https://a7c068bdc039499baa6defa9a85d7cce.gz3.agentos-app.net
本地运行：用任意静态服务器打开目录即可，例如 python -m http.server 后访问 demo/index.html
演示页默认展示离线 mock 演示数据；在页面顶部填入你运行中的后端地址（默认 http://localhost:8000）并点「测试连接」，即可切换为实时数据

🧪 测试

pip install pytest pytest-asyncio
pytest -q

测试全部基于 mock provider，无需网络与 API key 即可通过。

🗺️ 路线图（中等打磨阶段）

MCP Server 形态（analyze / screen / report / compare 四工具）
多标的对比（/compare + compare_stocks）
组合工具 research_company（分析+简报+同业对比，Agent 编排落地）
Remote MCP（SSE 传输，云端可被远程 Agent 调用）
交互式演示页 demo/（带图表，最利于传播）
新闻/公告情绪分析接入
技术指标（MACD/KDJ）计算层
Streaming 流式选股过程

📄 License

MIT