# 基于python的财经智能分析助手

**Repository Path**: pasionfru/finance_agent

## Basic Information

- **Project Name**: 基于python的财经智能分析助手
- **Description**: 一个面向股票研究与财经分析的智能 Agent 项目，支持 Web 对话、MCP 工具接入和本地部署。

它可以帮助你完成个股信息查询、历史行情分析、新闻追踪、分析师评级查看、多股横向对比等任务，并以更适合阅读的卡片式前端页面输出研究结论。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-18
- **Last Updated**: 2026-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Finance Agent

![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=flat-square&logo=python&logoColor=white)
![FastAPI](https://img.shields.io/badge/FastAPI-Web_API-009688?style=flat-square&logo=fastapi&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-111827?style=flat-square)
![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker&logoColor=white)

一个面向股票研究与财经分析的智能 Agent 项目，支持 Web 对话、MCP 工具接入和本地部署。

它可以帮助你完成个股信息查询、历史行情分析、新闻追踪、分析师评级查看、多股横向对比等任务，并以更适合阅读的卡片式前端页面输出研究结论。

## 项目亮点

- 基于 `FastAPI + LangChain + MCP` 构建，架构清晰，便于扩展
- 支持 `Claude Desktop / MCP Client` 调用，可直接作为财经工具服务使用
- 提供 Web 前端，支持 SSE 流式输出、工具调用过程展示、服务健康检查
- 内置股票信息、历史行情、财经新闻、分析师推荐、多股对比等核心能力
- 已补充 Docker 部署配置，适合本地开发和演示环境快速启动

## 适用场景

- 盘前快速梳理个股基本面
- 盘中查看新闻驱动与市场情绪
- 盘后复盘某只股票或某个板块
- 做投资研究时快速生成第一版分析框架
- 为 MCP 客户端提供财经类工具能力

## 功能概览

当前项目主要包含两种使用方式：

### 1. Web 研究助手

- 对话式输入问题
- 实时查看分析过程和工具调用
- 自动渲染 Markdown 结论卡片
- 展示服务状态与北京时间

### 2. MCP 工具服务

适合接入 Claude Desktop 或其他支持 MCP 的客户端，当前默认暴露的核心工具包括：

- `get_stock_info`：获取股票基本信息和关键指标
- `get_stock_history`：获取历史价格数据和近期走势
- `search_financial_news`：搜索财经新闻
- `get_stock_news`：获取某只股票的相关新闻
- `compare_stocks`：多只股票横向对比
- `get_recommendations`：查看分析师评级与目标价

## 技术架构

```text
Browser / Claude Desktop
          |
          v
  FastAPI Web API / MCP Client
          |
          v
      MCP over stdio
          |
          v
   agents/mcp_server.py
          |
          v
 yfinance / DuckDuckGo Search / LLM
```

项目中的主要链路是：

- 前端通过 `/api/chat/stream` 与后端进行 SSE 流式通信
- FastAPI 服务在启动时作为 MCP Client 连接本地 `agents/mcp_server.py`
- MCP Server 暴露财经工具
- LLM 结合工具结果生成中文分析结论

## 目录结构

```text
finance_agent/
├─ api/
│  └─ server_with_mcp.py        # FastAPI 服务，作为 MCP Client
├─ agents/
│  ├─ mcp_server.py             # MCP Server，暴露财经工具
│  ├─ analysis_agent.py         # 分析 Agent 示例
│  ├─ research_agent.py         # 预留扩展
│  └─ multi_agent_system.py     # 预留扩展
├─ static/
│  ├─ index.html                # 前端页面
│  ├─ style.css                 # 样式文件
│  └─ app.js                    # 前端交互与流式渲染
├─ finance_agent.py             # 单文件版 Agent 逻辑与提示词
├─ mcp_config.json              # MCP 配置示例
├─ pyproject.toml               # 项目依赖
├─ uv.lock                      # uv 锁定依赖
├─ Dockerfile                   # Docker 镜像构建
├─ docker-compose.yml           # Docker Compose 部署
└─ README.MD
```

## 快速开始

### 环境要求

- Python `3.12+`
- 建议使用 `uv`
- 如需 Docker 部署，请先安装并启动 Docker Desktop

### 方式一：本地运行

1. 克隆项目

```bash
git clone <your-repo-url>
cd finance_agent
```

2. 安装依赖

```bash
pip install uv
uv sync
```

3. 配置模型环境变量

Windows PowerShell：

```powershell
$env:ZHIPU_API_KEY="你的智谱 API Key"
$env:MODEL_NAME="glm-5"
$env:ZHIPU_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"
```

macOS / Linux：

```bash
export ZHIPU_API_KEY="你的智谱 API Key"
export MODEL_NAME="glm-5"
export ZHIPU_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"
```

4. 启动 Web 服务

```bash
uv run python api/server_with_mcp.py
```

5. 打开浏览器

```text
http://127.0.0.1:8000
```

### 方式二：Docker 部署

1. 复制环境变量模板

```bash
cp .env.example .env
```

Windows 下也可以直接手动新建 `.env` 文件。

2. 编辑 `.env`，至少填写：

```env
APP_PORT=8000
ZHIPU_API_KEY=your_zhipu_api_key
ZHIPU_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
MODEL_NAME=glm-5
```

3. 启动服务

```bash
docker compose up --build -d
```

4. 访问页面

```text
http://localhost:8000
```

## Claude Desktop / MCP 接入

项目已提供一个本地 `mcp_config.json` 示例。

如果你希望在 Claude Desktop 中接入本项目，可以参考下面的配置结构，并将路径改成你自己机器上的实际路径：

```json
{
  "$schema": "https://modelcontextprotocol.io/schemas/config.json",
  "mcpServers": {
    "finance-agent": {
      "type": "stdio",
      "command": "E:\\ai\\finance_agent\\.venv\\Scripts\\python.exe",
      "args": [
        "E:\\ai\\finance_agent\\agents\\mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "E:\\ai\\finance_agent"
      }
    }
  }
}
```

配置完成后，Claude Desktop 就可以把本项目当作财经工具服务来调用。

## API 说明

### Web 页面

- `GET /`：前端首页

### 系统接口

- `GET /api/health`：健康检查
- `GET /api/tools`：查看当前可用工具

### 对话接口

- `POST /api/chat`：非流式对话
- `GET /api/chat/stream?message=...`：SSE 流式对话

### 文档地址

- `GET /docs`：Swagger UI
- `GET /redoc`：ReDoc

## 示例提问

- `帮我分析一下贵州茅台的基本面和估值`
- `对比苹果和微软的股票，重点看营收增长和估值`
- `最近半导体板块有哪些值得关注的新闻`
- `查询特斯拉最近 3 个月的股价表现`
- `分析一下宁德时代当前可能的风险点`

## 配置说明

当前项目支持以下核心环境变量：

- `ZHIPU_API_KEY`：必填，智谱模型 API Key
- `ZHIPU_BASE_URL`：可选，默认 `https://open.bigmodel.cn/api/paas/v4/`
- `MODEL_NAME`：可选，默认 `glm-5`
- `HOST`：Web 服务监听地址，默认 `0.0.0.0`
- `PORT`：Web 服务端口，默认 `8000`
- `LOG_LEVEL`：日志级别，默认 `info`

## 常见问题

### 1. 启动时报 `未配置 ZHIPU_API_KEY 环境变量`

说明后端没有读取到模型密钥。请先设置 `ZHIPU_API_KEY` 后再启动服务。

### 2. `docker build` 或 `docker compose up` 失败

请先确认 Docker Desktop 已启动，并且 Linux Engine 正常运行。

### 3. Claude Desktop 调用 MCP 失败

请重点检查：

- `command` 是否指向正确的 Python 路径
- `args` 是否指向正确的 `agents/mcp_server.py`
- `PYTHONPATH` 是否设置为项目根目录
- 当前虚拟环境是否已经安装项目依赖

### 4. 工具调用没有返回结果

财经数据主要依赖 `yfinance` 和搜索接口，网络不稳定、接口限流或目标数据源异常时，可能会导致响应变慢或查询失败。

## 后续可扩展方向

- 增加财报解析和可视化图表能力
- 接入更多中文财经数据源
- 完善多 Agent 协作研究流程
- 增加用户会话记录与研究报告导出
- 支持更丰富的策略研究模板

## 说明

本项目适合用于学习和演示 `AI Agent + MCP + FastAPI + 财经工具` 的组合实践。

AI 输出内容仅供参考，不构成任何投资建议。