ZFundPilot MCP server
Commit Nov 14, 2026A self-hosted China fund portfolio analyzer that automates NAV synchronization, risk analytics, and provides AI-driven investment insights.
Also known as Euzohn/ZFundPilot
- Stars
- 29
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is ZFundPilot MCP?
ZFundPilot is a self-hosted China fund portfolio analyzer that automates NAV synchronization, risk analytics, and provides AI-driven investment insights.
Summary generated from the project's README
About ZFundPilot MCP server
Managing China fund portfolios with automated data synchronization and risk analytics is what ZFundPilot enables for individual investors. This self-hosted system allows users to track transactions across multiple channels like Alipay and Tiantian Fund while maintaining complete data ownership through local or Docker deployments. It automates the process of fetching Net Asset Values using AkShare and Tiantian Fund as a fallback, ensuring your holdings are always up to date.
Developers and investors can use this tool to perform deep quantitative analysis, including XIRR annualized returns, industry exposure penetration, and DCA backtesting. The system distinguishes itself by offering an MCP-compatible layer and independent Agent tokens, allowing AI clients like Claude Desktop or Cursor to interact with your portfolio within strict read-only or controlled-write boundaries. This setup provides AI-driven insights and transaction recording without exposing your entire API to the model.
What you can do with it
- 1Automate transaction data entryUse natural language to describe a fund purchase or sale and let the AI parse the structured data and calculate fees.
- 2Backtest investment strategiesCompare the performance of a regular investment plan against a lump-sum investment using historical net asset values.
- 3Monitor inflation-adjusted wealthDetermine if your portfolio returns are actually outpacing inflation by overlaying CPI and M2 wealth benchmarks.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableeuzohn/zfundpilot is public and reachablegithub.com/euzohn/zfundpilot ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/euzohn/zfundpilot ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub🌐 简体中文 | English
⚠️ 仅用于数据分析与风险管理,不做自动交易、不预测涨跌、不构成任何投资建议。
🚧 本项目处于活跃开发阶段。功能可能会发生变化,某些功能也可能会失效。如果您遇到问题或有好的想法,请提交 Issue。欢迎贡献代码!
截图
这是什么
ZFundPilot 是一个自托管的中国基金组合分析工具。记录每一笔交易,自动拉取净值,计算收益与风险,给出结构优化建议。不是交易系统,不做自动买卖,不连接券商。
为什么不同
- 自托管,数据归你 — 本地运行或 Docker 部署,数据存在自己手里,不上传任何第三方
- 中国市场专精 — 数据源来自 AkShare 和天天基金,支持中国基金的全维度分析(含实时估值、费率计算、板块分类)
- 数据驱动分析 — 不是荐基平台,没有排行榜和营销话术,只有基于你持仓数据的量化指标
- AI 辅助,不是 AI 决策 — OpenAI 兼容 API 提供持仓上下文问答,建议仅供参考,决策在你自己
- Agent 可读,也可审计 — 独立 Agent token + MCP 适配层,让 Claude Desktop / Cursor 在明确的 scope、限流与审计边界内读取组合、维护自选、提交待审批提案或(可信 Token)直接记录已确认的单笔交易,而不是把整站 API 暴露给模型
快速开始
Docker(最快)
docker compose up -d --build
浏览器打开 http://localhost:8000
本地开发
# 后端 API
pip install -e .
uvicorn zfundpilot.api:app --reload --port 8000
# 前端开发服务器(另一个终端)
cd frontend && npm install && npm run dev
详细部署指南见 DEPLOY.md。
功能亮点
交易与持仓
- 交易流水管理 — 记录买入/卖出/分红/再投资/转换,表单录入 + CSV 批量导入/导出 + 全量数据备份导出 ZIP(格式 v2,含净值历史与逐表校验,可预检后恢复)
- 基金转换 — 一次录入转出基金(卖出)和转入基金(买入),原子创建两条关联交易,转出份额带持有量校验,赎回费/申购费分别自动计算,转换记录在流水中带标识,点击标识可跳转配对腿详情
- 多渠道支持 — 支付宝、理财通、天天基金等,同一基金不同渠道分开计算成本
- 手续费自动查询 — 录入交易时自动从天天基金拉取申购/赎回费率,按金额分档匹配,卖出按 FIFO 计算赎回费,支持手动覆盖
- 持仓自动汇总 — 按「基金 + 渠道」用移动加权平均成本法汇总,卖出时结转已实现收益
- 持仓明细视图 — 列表视图(跨渠道明细 + 净值新鲜度 + 自定义展示列)与网格视图(Bento 大卡 + 占比条 + 成本/估值/盈亏/持仓天数/板块)自由切换
- 行业穿透(基金穿透) — 跨基金聚合底层持仓的真实行业敞口(证监会分类),揭示组合真实行业分布而非基金名称推导。持仓页行业敞口 Tab 含穿透覆盖度、BarChart + PieChart + 明细表;基金详情页展示单基金行业配置饼图。AI 投顾上下文注入行业穿透数据
分析与估值
- 净值更新 — AkShare 优先,天天基金兜底,输入代码自动获取名称/类型/板块
- 收益分析 — 浮动盈亏、已实现盈亏、XIRR 年化收益(组合 + 单基金,现金流二分法)、组合收益曲线、基准对比(沪深300/上证指数/创业板指 + CPI 购买力/M2 财富排位水位线,数据持久化离线可用)、收益率排序(累计/年化切换)、日/周/月/年日历视图、按渠道堆叠柱状图
- 财富水位线(CPI/M2) — 组合收益曲线叠加通胀购买力线(CPI 环比链乘价格水平)与社会财富排位线(M2 存量扩张),回答「扣掉通胀我真的变富了吗」。水位线以建仓日前最后月末为基期,建仓日精确为 0。AI 投顾上下文注入实际收益(扣通胀)与社会财富排位升降
- 实时估值 — 交易日实时估算基金涨跌幅,组合估算 P&L 一目了然,真实净值公布后自动失效。主源无数据时自动走天天基金 fundgz 替补(6 线程并行),指数/ETF 行情兜底
- 基金对比 — 多维度同框对比 + 净值走势叠加 + 相关性矩阵。对比篮全局管理,随时增减,导航栏显示数量 badge
- 基金筛选器 — 从全市场基金池按类型/板块/关键词筛选,Top 30 自动补充收益/风险指标,列头可排序,一键加入对比或自选
- 自选关注列表 — 追踪关注基金,已持有的自动标「持仓中」badge,列头可排序,添加代码自动获取名称/类型/板块,快捷跳转详情/对比/买入
- 截图导入 — 上传购买记录或持仓截图,AI 视觉模型自动识别交易/持仓。持仓对账模式按渠道对比已记录份额,一键生成差额调整交易。视觉模型独立配置(智谱 GLM-4V / 通义千问 VL / GPT-4o / Kimi 视觉),截图只有名称时自动匹配代码
- 基金详情 — 净值走势 + 资产配置饼图 + 前十大重仓股 + 同类排名走势 + 基金档案(基金经理/规模/成立时间)+ 风险等级 + 顶栏快捷入口(加入对比/自选/买入/卖出/定投)
- 定投策略回测 — 指定基金 + 时间区间 + 频率(月/双周/周),用历史净值回测定投 vs 一次性投入,计算 XIRR 年化、最大回撤、夏普比率
- 定投计划自动执行 — 设置每日/每周/每双周/每月自动买入,遇非交易日顺延(A 股交易日历,含法定节假日/调休),自动计算手续费,T+1 回填净值。执行前校验基金申购状态(暂停申购/限购/低于起点自动跳过,次日重试)
组合体检与优化
- 组合体检 — 四维诊断评分(配置/风险/流动性/收益,每维 0-100)+ 综合定级(优秀→危险),复用风险指标 + 结构建议,一个 API 返回全量
- 结构建议 — 基于组合结构给出再平衡建议(非交易指令)
- 止盈止损提醒 — 净值更新后自动检查持仓收益率,达到阈值时生成提醒。状态机防重复:触发后需收益率回落到复位线以下才再次提醒,避免部分止盈后重复骚扰。止盈/止损独立开关,全局阈值可配置。确认跳转交易页预填卖出
- 分红自动检测 — 每天 09:30 自动扫描持仓基金分红事件,弹窗预填确认入账。幽灵提醒自动清理:源数据修正后自动标记无效提醒为 ignored
- 风险等级展示 — 基金风险等级(低/中低/中/中高/高)持久化后全站展示:持仓列表风险色点 badge + 风险等级筛选 + 语义排序,纵览页风险分布饼图,收益页单基金色点,组合体检页风险等级分布占比条
AI 辅助
- AI 投顾对话 — 配置 OpenAI 兼容 API(智谱/Kimi/通义千问/DeepSeek),AI 自动联网搜索最新资讯 + 结合持仓数据给出调仓建议
- AI 录入交易 — 自然语言描述交易,AI 自动解析结构化数据并计算手续费,确认后写入
Agent 接入(API / MCP)
- 独立 Agent 令牌 — 与网页登录 token 物理隔离的高熵 token,服务端只存 SHA-256 摘要;按只读与可选写 scope 授权,默认拒绝、可撤销/过期,无密码模式下不可签发
- 20 个只读工具 — 组合汇总、数据状态、持仓、基金详情、体检、收益、对比、流水、自选、提醒、计划、曲线、基准、风险、行业敞口、检索、筛选、回测与能力发现;统一响应包与正式净值口径,不暴露任何写接口
- 写开关总闸 — Agent 写能力默认关闭,网页「设置 → Agent 接入」可随时开关(需登录密码确认、持久化、重启保持),无密码模式禁止开启
- 受控写入 — 自选维护(
watchlist:write)与净值/元数据刷新(data:refresh)直接执行;record_transaction(transactions:create)在限额内直记已确认的单笔买卖,预检异常自动降级为待审批提案 - 账本/计划/提醒处理提案 —
create_operation_proposal等 4 个工具按transactions:propose/plans:propose/alerts:proposescope 只提交待审批提案;管理员网页确认后服务端在同一事务内复核并写入账本/计划/提醒状态,永不绕过审批;修改/删除/启停/提醒处理/回填/定投手动执行用row_digest版本前置防并发覆盖。定投手动执行只新增一笔买入并推进计划簿记,不重算next_run、不触发调度器 - CSV/截图预检、对账与回填预检 — 提交提案前先校验 CSV/条目与持仓对账,或盘点可回填净值的候选流水,只返回报告,不写账本、不联网、不创建提案
- MCP 适配层 — 可选 stdio 桥接(
python -m zfundpilot.mcp_server),让 Claude Desktop / Cursor 在 scope 边界内调用,鉴权/scope/限流复用 HTTP 入口 - 可审计边界 — 鉴权成功/失败、限流、签发与撤销均写审计(仅记 token 前缀),按 token + 端点限流,远程访问要求 HTTPS;所有响应带
X-Request-ID,错误体提供稳定error.code与retryable。端点、示例与配置见 docs/AGENT_API.md
安全与自定义
- 密码认证 — 用户名 + 密码登录,HMAC 签名 token,bcrypt 密码哈希,登录速率限制防爆破
- API Key 加密存储 — AI API key 落盘自动加密(Fernet AES-128-CBC + HMAC-SHA256),主密钥
data/secret.key权限 0o600;加密用于防止单个配置文件被直接读取,无法防止整个data/目录被读取,请限制目录权限。远程 AI 端点要求 HTTPS,明文 HTTP 仅允许本机回环地址 - 审计日志 — 敏感操作记入日志,设置页可查看
- 中英文切换 — 全站界面支持中英文切换,侧边栏一键切换,数据格式(¥/$、相对时间)自动适配
- 涨跌颜色切换 — 支持「绿涨红跌(国际)」/「红涨红跌(A 股)」双主题,服务端同步
- 暗色模式 — light/dark/system 三态切换,默认跟随系统偏好
- 渠道颜色自定义 — 预设色板 + 自由选色,服务端同步
- 关键词映射自定义 — 板块/类型分类规则开放给用户编辑,多设备同步
使用流程
- 交易录入 → 输入基金代码,自动补全信息,选择操作类型和渠道,保存
- 净值更新 → 点击「更新全部基金净值」拉取历史数据,或启用定时任务自动更新
- 持仓与分析 → 查看持仓明细、收益曲线、风险指标与结构建议
- AI 辅助 → 配置 API 后对话咨询,或让 AI 帮你录入交易
买入填金额(净值自动填充,份额自动倒算),卖出填份额(金额自动倒算),分红填金额,再投资填份额+净值。
技术栈
| 层 | 技术 |
|---|---|
| 前端 | React 18 + Vite + TypeScript + Tailwind + shadcn/ui |
| 后端 | FastAPI + SQLite + Pandas |
| 数据源 | AkShare + 天天基金 |
| AI | OpenAI 兼容 API(智谱 / Kimi / 通义千问 / DeepSeek) |
| 部署 | Docker / Uvicorn |
项目结构
ZFundPilot/
├── pyproject.toml # 打包配置、依赖、Ruff/Pytest 配置
├── Dockerfile # 多阶段构建 Docker 镜像(内置 TZ=Asia/Shanghai)
├── docker-compose.yml # Docker 部署(端口由 override 指定)
├── .github/workflows/ # GitHub Actions CI/CD
│ └── ci.yml # ruff → pytest → tsc → build
├── src/zfundpilot/ # Python 包
│ ├── __init__.py
│ ├── config.py # 全局配置、渠道、风险阈值、认证/AI 配置存储
│ ├── models.py # 数据结构(Fund / Transaction / Position)
│ ├── db.py # SQLite 数据库操作
│ ├── fetch_fund.py # 净值获取 + 名称/类型/板块识别 + 费率查询 + 关键词映射 + 持仓/排名/档案/行业配置
│ ├── fetch_estimate.py # 基金实时估值(AkShare fund_value_estimation_em)
│ ├── fetch_macro.py # 宏观财富水位(CPI 价格水平 + M2 存量)
│ ├── compare.py # 基金对比(收益率/风险/相关性多维度计算)
│ ├── fund_filter.py # 基金筛选器(全市场池加载 + 多条件筛选 + 指标增强 Top 30)
│ ├── analysis.py # 交易流水汇总、收益计算、组合曲线、行业穿透聚合
│ ├── returns.py # XIRR 年化收益率(现金流二分法 + 现金流构建)
│ ├── risk.py # 风险分析(回撤/波动率/集中度/结构占比)
│ ├── health.py # 组合体检(四维评分:配置/风险/流动性/收益)
│ ├── rebalance.py # 结构优化建议
│ ├── backtest.py # 定投策略回测
│ ├── auto_invest.py # 定投计划自动执行
│ ├── crypto.py # 敏感字段加密(Fernet)
│ ├── backup_service.py # 备份格式 v2、预检与事务化恢复
│ ├── data_io.py # CSV 导入/导出(备份兼容入口)
│ ├── api.py # FastAPI REST API(37+ 路由 + 认证中间件)
│ ├── ai.py # AI 投顾对话(持仓上下文 + 联网搜索 + LLM 流式调用)
│ └── scheduler.py # APScheduler 定时净值更新 + 定投执行 + 分红检测 + 止盈止损检查
├── tests/ # Pytest 测试套件(542 个用例)
│ ├── conftest.py # 共享 fixtures
│ └── test_*.py # 26 个测试模块
├── data/
│ ├── fund.db # SQLite 数据库(自动生成)
│ ├── auth.json # 用户名 / 密码哈希 / token 密钥(自动生成)
│ ├── ai_config.json # AI 模型配置(自动生成)
│ └── sector_map.json # 基金代码→板块映射(自动维护)
├── frontend/ # React + Vite + TypeScript + Tailwind + shadcn/ui
│ ├── src/
│ │ ├── pages/ # 13 个页面
│ │ ├── components/ # Layout + shadcn/ui + 业务组件
│ │ ├── i18n/ # LanguageContext + zh.ts + en.ts 翻译文件
│ │ ├── api/ # 类型化 API client + streamChat (SSE)
│ │ └── lib/ # 工具函数(format/actionLabels/rangeLabels 按 lang 切换)
│ └── dist/ # 构建产物(生产模式)
├── assets/readme/ # README 视觉素材
└── .env.example # 环境变量模板
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
ZFUNDPILOT_USERNAME |
admin |
仅首次启动时初始化登录用户名 |
ZFUNDPILOT_PASSWORD |
空 | 仅首次启动时初始化密码哈希(bcrypt) |
ZFUNDPILOT_SECRET |
自动生成 | 仅首次启动时初始化 token 签名密钥 |
ZFUNDPILOT_NAV_CRON |
0 21 * * 1-5 |
净值定时更新 cron 表达式 |
ZFUNDPILOT_HOME |
项目根 | 数据目录所在位置 |
ZFUNDPILOT_TRUSTED_PROXIES |
空 | 信任代理网段(仅 Nginx/Caddy 反代后配置) |
CONTAINER_NAME |
zfundpilot |
Docker 容器名称,多实例部署时需为每个实例设置不同名称(详见 DEPLOY.md) |
安全
| 措施 | 说明 |
|---|---|
| 密码哈希 | bcrypt(cost=12),兼容旧版 SHA-256,登录后自动升级 |
| 登录限流 | 5 分钟内失败 5 次锁定 15 分钟 |
| Token 认证 | HMAC-SHA256 签名,7 天有效期,改密后立即失效 |
| Agent token | 独立高熵随机串,仅存 SHA-256 摘要,scope 白名单默认拒绝,可撤销/过期 |
| 错误脱敏 | AI 上游错误不暴露给客户端 |
| 信任代理 | ZFUNDPILOT_TRUSTED_PROXIES 控制,默认空(不信任任何代理) |
- 纯 IP / 局域网:设密码即可,默认配置安全
- 域名 + HTTPS:推荐 Caddy 自动 TLS,配置
TRUSTED_PROXIES - Agent token:仅通过
Authorization: Bearer传递,不要放进 URL、前端持久存储或模型提示词;远程使用必须走 HTTPS
CSV 列说明(交易流水)
| 列名 | 说明 | 必填 |
|---|---|---|
| fund_code | 基金代码 | ✅ |
| action | 操作类型(买入/卖出/分红/再投资,也识别 buy/sell/dividend/reinvest) | ✅ |
| date | 成交日期 YYYY-MM-DD | ✅ |
| amount | 成交金额 | 买入/分红必填 |
| shares | 成交份额 | 卖出/再投资必填 |
| nav | 成交净值 | 填二缺一可自动补全 |
| fee | 手续费 | |
| channel | 渠道 | |
| note | 备注 |
amount / shares / nav 填写任意两列即可,自动补全第三列。支持中文表头。
风险阈值
| 指标 | 默认阈值 |
|---|---|
| 单基金占比偏高 / 过高 | 20% / 40% |
| 债券最低占比 | 10% |
| QDII 海外暴露 | 30% |
| 权益类偏重 | 70% |
| 高风险回撤 | -15% |
| 高波动率 | 25% |
默认阈值定义在 config.py 的 RiskThresholds,可按需调整。
更新日志
详见 CHANGELOG.md。
贡献
欢迎提交 Issues 报告问题或提出新需求,也欢迎提交 Pull Requests 一起改进。
作者邮箱:Zongid@outlook.com
License
MIT License © 2025 Euzohn
数据来源与合规声明见 NOTICE.md。
Star History
ZFundPilot MCP questions
Is this a trading system?
No, it is a data analysis and risk management tool. It does not perform automatic trading or connect to brokers.
Can I use AI to manage my portfolio?
Yes, it supports OpenAI-compatible APIs to provide context-aware portfolio Q&A and investment suggestions, though final decisions remain yours.