wealthapi

wealthapi-mcp

一个轻量的 Model Context Protocol（MCP） 服务，可让 Claude（或任何兼容 MCP 的助手）回答有关你 wealthAPI 账户的日常投资组合问题：

“上个月我在哪方面花的钱最多？” “今年我的投资组合表现如何？” “列出我的五大持仓。” “我的哪些投资价值下跌最多？”

它在你的计算机上本地运行。你的持有者令牌绝不会离开你的计算机。

什么是 MCP 服务？

MCP 是一种开放协议，可让 AI 助手调用由你控制的工具。助手在一个进程中运行（例如 Claude Desktop）；MCP 服务则作为单独的进程运行，由你启动。两者通过 stdio 使用 JSON-RPC 进行通信：助手向服务的 stdin 写入一条 tools/call 消息，服务运行工具并将结果写入 stdout。协议就是这么简单。

请注意两者的区别：这是一个 MCP 服务，而不是 MCP 插件。MCP 插件并不存在——插件（例如 Claude Code 插件）扩展的是助手本身，而 MCP 服务是一个独立进程，助手通过协议连接到它。任何兼容 MCP 的客户端（Claude Desktop、Claude Code 等）都可以使用此服务。

具体来说，这个代码仓库是一个 Node 脚本。Claude Desktop 启动它时，脚本会注册其工具，等待工具调用；收到调用后，会代表你向 wealthAPI REST API 发起 HTTPS 请求，并返回文本摘要。无状态、无数据库，也无需维护服务。

更多信息请访问 https://modelcontextprotocol.io。

工具

身份验证使用 wealthAPI API 令牌（wapi_key_…），并具备读取权限范围（accounts:read、investments:read、transactions:read、profile:read）。所有工具均为只读。

账户与现金流

工具	封装的接口	可回答的问题
list_accounts	GET /api/v1/accounts	“我有哪些账户？”
get_account_balances	GET /api/v1/accounts/balances	“显示我的现金余额历史记录”
get_portfolio_valuation	GET /api/v1/accounts/valuation（+ historicValuations）	“我的投资组合价值是多少（今天／随时间变化）？”
list_transactions	GET /api/v1/transactions	“上个月我在哪方面花的钱最多？”
detect_recurring_transactions	GET /api/v1/transactions	“我有哪些订阅／固定支出？”
list_bookings	GET /api/v1/bookings	“显示我的买入／卖出／股息”
get_cash_flow_summary	GET /api/v1/cashFlowAnalytics/history	“每月收入与支出对比”
get_savings_rate	GET /api/v1/cashFlowAnalytics/history	“我的储蓄率是多少？”

投资组合与表现

工具	封装的接口	可回答的问题
list_investments	GET /api/v2/investments	“我持有哪些投资，它们价值多少？”
get_gainers_and_losers	GET /api/v1/investments/gainersAndLosers	“表现最佳／最差的投资”
get_portfolio_performance	POST /api/v2/performance	“今年我的投资组合表现如何？”
get_portfolio_allocation	GET /api/v1/investments	“按地区／行业／资产类型划分，我的投资组合有多分散？”
get_risk_metrics	GET /api/v1/riskYieldMetrics（+ /investments）	“我的投资组合风险有多大？”
get_realized_gains	GET /api/v1/performance/realizedGains	“我今年实现了多少收益？”（报税季）

股息

工具	封装的接口	可回答的问题
get_dividend_history	GET /api/v1/dividends/history	“我每年／每月获得了多少股息收入？”
get_dividend_calendar	GET /api/v1/dividends/calendar	“我下一次股息支付是什么时候？”
get_portfolio_yield	GET /api/v1/dividends/portfolioYield	“我的股息收益率是多少？”

市场数据与概况

工具	封装的接口	可回答的问题
search_symbols	GET /api/v2/symbols	“查找 Apple / 此 ISIN”
get_quotes	GET /api/v2/quotes	“当前价格是多少？”
get_security_fundamentals	GET /api/v1/fundamentals/{isin}（以及 /statistics）	“这只股票贵吗？”（P/E、P/B、F-Score）
whoami	GET /api/v1/users/myself	“这是哪个账户？”

服务器还会注册提示词（monthly_review、savings_rate_check、 subscription_audit、fixed_costs_summary、financial_health_check），将这些 工具串联起来，提供引导式分析。

工具注册由 src/index.ts 中的 SUPPORTED_TOOLS/SUPPORTED_PROMPTS 控制 — 在此移除某个名称即可禁用对应功能，无需删除代码。

安装

需要 Node 20+ 和 pnpm。

git clone [email protected]:wealthAPI-eu/wealthapi-mcp.git
cd wealthapi-mcp
pnpm install
pnpm build

从 wealthAPI 获取个人 bearer token（进入你的账户 → API 设置）。

将服务器添加到 Claude Desktop 的配置中 （macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "wealthapi": {
      "command": "node",
      "args": ["/absolute/path/to/wealthapi-mcp/build/index.js"],
      "env": {
        "BEARER_TOKEN": "paste-your-token-here"
      }
    }
  }
}

重启 Claude Desktop。启用的工具会显示在任意聊天的工具面板中， 你可以用通俗的英语询问投资组合相关问题。

如何添加新工具

src/tools/accounts.ts 中提供了标准示例 — list_accounts 约 50 行代码， 展示了完整的实现模式。

1. 在 src/tools/ 下创建或打开相关文件，并编写一个 register*Tools(server, client) 函数，调用 server.registerTool(...)。 每次调用都需要传入名称、{ description, inputSchema } 对象（输入架构使用 Zod）， 以及一个异步处理程序，返回 { content: [{ type: "text", text }] }。
2. 从 src/index.ts 导入并调用你的 register*Tools。
3. 运行 pnpm build 并重启 Claude Desktop。

就是这么简单。无需代码生成、注册文件或样板代码。

目录结构

src/
  index.ts          Bootstrap: McpServer + StdioServerTransport + register*Tools(...)
  config.ts         Reads BEARER_TOKEN from env; API base URL is fixed to production
  api/
    client.ts       fetch wrapper: GET/POST, query strings, retry on 5xx/429
    types.ts        TS interfaces for API response shapes
  tools/
    accounts.ts     list_accounts, get_account_balances, get_portfolio_valuation
    allocation.ts   get_portfolio_allocation
    cash-flow.ts    get_cash_flow_summary, get_savings_rate, detect_recurring_transactions
    dividends.ts    get_dividend_history, get_dividend_calendar, get_portfolio_yield
    investments.ts  list_investments, get_gainers_and_losers
    performance.ts  get_portfolio_performance, get_realized_gains
    risk.ts         get_risk_metrics
    securities.ts   search_symbols, get_quotes, get_security_fundamentals
    transactions.ts list_transactions, list_bookings
    user.ts         whoami
  util/
    logger.ts       Pino → stderr (stdout is reserved for MCP)
    format.ts       formatCurrency, formatDate, formatTable
test/
  api/
    client.test.ts  Vitest unit test for the query-string builder
  tools/
    *.test.ts       Unit tests for the pure aggregation helpers

运行测试

pnpm test