wealthapi

wealthapi-mcp

Claude（またはMCP互換のアシスタント）がwealthAPIアカウントについて日常的なポートフォリオの質問に回答できる、小さな**Model Context Protocol（MCP）**サーバーです。

「先月、何に一番お金を使いましたか？」 「今年のポートフォリオのパフォーマンスはどうですか？」 「保有額が最も大きい銘柄を5つ見せてください。」 「最も価値が下がった投資はどれですか？」

お使いのマシン上でローカルに動作します。ベアラートークンがコンピューターの外に出ることはありません。

MCP サーバーとは？

MCPは、AIアシスタントが制御可能なツールを呼び出すためのオープンプロトコルです。アシスタントは1つのプロセス（例：Claude Desktop）で動作し、MCPサーバーは別のプロセスとして起動します。両者はJSON-RPCを使ってstdio経由で通信します。アシスタントがtools/callメッセージをサーバーの標準入力に書き込み、サーバーがツールを実行して、その結果を標準出力に書き戻します。プロトコルの仕組みはこれだけです。

違いにご注意ください。これはMCPサーバーであり、MCP プラグインではありません。MCPプラグインというものはありません。プラグイン（例：Claude Codeのプラグイン）はアシスタント自体を拡張するもので、MCPサーバーはアシスタントがプロトコル経由で接続する独立したプロセスです。MCP互換のクライアント（Claude Desktop、Claude Codeなど）であれば、このサーバーを利用できます。

具体的には、このリポジトリはNodeスクリプトです。Claude Desktopが起動すると、スクリプトはツールを登録してツール呼び出しを待ち受けます。呼び出しを受け取ると、ユーザーに代わってwealthAPI REST APIにHTTPSリクエストを送信し、テキストによる概要を返します。状態管理もデータベースもなく、維持管理するサーバーもありません。

詳しくはhttps://modelcontextprotocol.ioをご覧ください。

ツール

認証には、読み取りスコープ（accounts:read、investments:read、transactions:read、profile:read）を持つwealthAPI APIトークン（wapi_key_…）を使用します。すべてのツールは読み取り専用です。

アカウントとキャッシュフロー

ツール	呼び出し先	回答できる質問
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 スコア）
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 から個人用ベアラートークンを取得します（アカウント → 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/ の関連ファイルを新規作成するか開き、server.registerTool(...) を呼び出す register*Tools(server, client) 関数を作成します。 各呼び出しには、名前、{ 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