项目简介

这是一个功能全面的Python工具，旨在帮助您管理和分析您的Questrade投资组合。它提供实时投资组合估值、内部收益率（IRR）计算、再平衡建议、专业的PDF报告生成，并支持自动化邮件发送。更重要的是，它集成了一个MCP服务器，允许LLM客户端（如Claude Desktop）通过标准化的接口调用其核心功能，实现智能化的投资辅助。

主要功能点

投资组合分析: 实时获取投资组合估值和资产配置明细。
业绩追踪: 按资产组别计算内部收益率（IRR）和具体ETF的收益。
再平衡建议: 根据您设定的目标资产配置，提供自动化再平衡建议。
PDF 报告: 生成包含图表和分析的专业投资报告。
交易历史: 查询特定ETF的详细交易历史，并追踪成本基础。
MCP 服务器: 提供标准化接口，允许外部LLM客户端调用上述投资管理功能。
鲁棒性: 包含自动令牌刷新、API重试逻辑和错误处理，确保稳定运行。
多币种支持: 支持CAD/USD货币转换和每日外汇汇率。

安装步骤

克隆仓库:

git clone https://github.com/ScarpVS/questrade-portfolio-tool.git
cd questrade-portfolio-tool

安装依赖: 使用'uv'工具安装项目依赖。
```
uv install
```

配置环境变量: 在项目根目录创建 '.env' 文件，并填入您的Questrade API凭据和可选的邮件设置：

# Questrade API 刷新令牌
QTRADE_REFRESH_TOKEN=your_refresh_token_here
# 是否使用模拟交易环境 (true/false)
QTRADE_PRACTICE=false

# 报告基础货币 (CAD/USD)
BASE_CURRENCY=CAD
# 默认USD/CAD汇率
USDCAD_RATE=1.35
# 可选: 日常汇率CSV文件路径
# FX_CSV=/path/to/your/fx_rates.csv

# 邮件设置 (可选，用于发送PDF报告)
# [email protected]
# [email protected]
# SMTP_HOST=smtp.your-provider.com
# SMTP_PORT=587
# SMTP_USER=your-smtp-user
# SMTP_PASS=your-smtp-password

配置资产类别 (可选): 修改 'categories.yaml' 文件，自定义您的资产分类和目标配置。

MCP 服务器配置

为了在MCP客户端（如Claude Desktop）中使用此服务器，您需要配置一个指向其启动脚本的服务器。以下是配置示例：

{
  "name": "Questrade Portfolio",
  "command": "uv",
  "args": [
    "run",
    "python",
    "-m",
    "qt_mcp.mcp_server"
  ],
  "env": {
    "PYTHONPATH": "src"
  },
  "description": "连接到您的Questrade账户，提供投资组合分析、报告生成、再平衡建议和交易历史查询功能。",
  "tools": [
    {
      "name": "portfolio_summary",
      "description": "获取指定日期范围内的完整投资组合表现总结，包含实际估值。",
      "parameters": {
        "start": { "type": "string", "description": "ISO格式的开始日期，如'2025-07-01'" },
        "end": { "type": "string", "description": "ISO格式的结束日期，如'2025-10-17'" }
      }
    },
    {
      "name": "portfolio_demo_summary_tool",
      "description": "获取指定日期范围内的投资组合总结，其中所有估值已归一化为百分比，适合隐私安全分享。",
      "parameters": {
        "start": { "type": "string", "description": "ISO格式的开始日期，如'2025-07-01'" },
        "end": { "type": "string", "description": "ISO格式的结束日期，如'2025-10-17'" }
      }
    },
    {
      "name": "generate_report",
      "description": "为指定日期范围生成详细的PDF投资报告，并可选择通过邮件发送。",
      "parameters": {
        "start": { "type": "string", "description": "ISO格式的开始日期，如'2025-07-01'" },
        "end": { "type": "string", "description": "ISO格式的结束日期，如'2025-10-17'" },
        "email": { "type": "boolean", "description": "是否发送邮件报告 (默认为 false)" }
      }
    },
    {
      "name": "rebalance",
      "description": "根据 categories.yaml 中的目标配置，计算投资组合的再平衡建议。",
      "parameters": {
        "start": { "type": "string", "description": "ISO格式的开始日期，如'2025-07-01'" },
        "end": { "type": "string", "description": "ISO格式的结束日期，如'2025-10-17'" },
        "min_trade": { "type": "number", "description": "建议的最小交易金额 (默认为 100.0)" }
      }
    },
    {
      "name": "etf_history",
      "description": "获取指定ETF的完整历史交易记录（买入/卖出），包含运行中的成本基础和持仓。",
      "parameters": {
        "symbol": { "type": "string", "description": "ETF股票代码，如 'VTI' 或 'ZCN.TO'" },
        "start": { "type": "string", "description": "ISO格式的开始日期，如 '2021-09-01' (默认为投资开始日期)" },
        "end": { "type": "string", "description": "ISO格式的结束日期，如 '2025-12-31' (默认为今天)" }
      }
    }
  ]
}

基本使用方法 (通过MCP客户端)

在配置好MCP服务器后，您可以在Claude Desktop等支持MCP的LLM客户端中直接通过自然语言或Tool Call指令与服务器交互。例如：

询问您的投资组合在某个时间段的表现： 'portfolio_summary start="2025-07-01" end="2025-10-17"' 或直接说：“帮我分析一下我从2025年7月1日到2025年10月17日的投资组合。”
获取一个隐私安全的百分比报告： 'portfolio_demo_summary_tool start="2025-07-01" end="2025-10-17"'
生成并发送一份PDF报告： 'generate_report start="2025-07-01" end="2025-10-17" email=true'
查询特定ETF的历史交易记录： 'etf_history symbol="VTI" start="2024-01-01" end="2024-12-31"' 或直接说：“告诉我VTI这支ETF在2024年的交易历史。”

关键词

项目简介

主要功能点

安装步骤

MCP 服务器配置

基本使用方法 (通过MCP客户端)

信息