okama-mcp

okama-mcp

okama の投資ポートフォリオツールキットと okama Planner を AI アシスタント（Claude Desktop、Claude Code、Cursor、Codex、その他の MCP 対応クライアント）に公開する MCP（Model Context Protocol）サーバーです。

okama-mcp をインストールすると、次のようなことを AI に依頼できます。

「過去15年間を対象に、金を30％、不動産を70％とするポートフォリオをバックテストしてください。」

「このポートフォリオについて、インフレ率に連動して毎月1,000ドルを取り崩す、25年間のモンテカルロ退職予測を実行してください。」

「SPY、BND、GLD と無リスク金利3％での接点ポートフォリオは何ですか？」

…すると AI は MCP ツールを使って okama を直接呼び出します。Python コードは不要です。

FastMCP を基盤としています。単一のコードベースで、2つのトランスポートに対応しています。 stdio（ローカルクライアント向け）と streamable-http（セルフホスト向け）です。 okama-mcp は無料のオープンソースです。ローカルまたは独自のサーバーで実行できます。HTTP トランスポートはセルフホスト向けです。mcp.okama.io が提供するのはプロジェクトの ランディングページであり、公開 MCP エンドポイントではありません。クライアントレジストリツールと Excel エクスポートには、 互換性のある Planner コンパニオンと、設定済みのローカル stdio インストールが必要です。

インストール

開発状況（2026年10月26日）： main は MCP 3.1.0 と Planner 0.5.0 の準備中で、どちらのバージョンもまだ公開されていません。以下のソースからのセットアップを使用してください。 PyPI では引き続き MCP 3.0.0 と Planner 0.4.1 が提供されており、以前の契約に基づいています。

Python ≥ 3.11（okama 自体と同じ最低バージョン）が必要です。また、okama ≥ 4.0.0 と okama-planner[reports]>=0.5.0,<0.6.0 が必要です。

クライアントデータモード（ソースチェックアウト）： ローカル MCP は、デフォルトで匿名読み取りに対応します。 client_data_mode_set({"mode":"personal_data"}) を実行するとクライアントの完全な CRUD が有効になり、 {"mode":"anonymous"} を実行するとクライアントへの書き込みが再び無効になります。この設定はデータベースごとに接続をまたいで保持されます。 uv sync は、必要なアクセス API を備えた Planner 0.5.0 の固定ソースリビジョンをインストールします。PyPI では引き続き Planner 0.4.1 が提供されるため、互換性のあるコンパニオンが公開されるまでは、準備済みリリースを公開できません。 インストールとリリースのゲートを参照してください。 Market および finplan_* ツールは引き続き独立して利用できます。以前のリリースでの動作については、 3.0 移行ノートを参照してください。

最も簡単な方法は、クローンも仮想環境も不要な uv または pipx です。

uvx okama-mcp stdio          # run straight from PyPI
# or
pipx install okama-mcp

通常の pip も使用できます。

pip install okama-mcp

警告

_{pip を使う場合は、専用の仮想環境を使用してください。最近の Linux ディストリビューションの多くでは、システム Python が外部管理対象としてマークされています（PEP 668）。そのため、仮想環境外での pip install は失敗し、共有環境では依存関係の競合が発生するおそれがあります。MCP クライアントの設定では、command に仮想環境内の okama-mcp スクリプトの絶対パスを指定してください。GUI クライアントからはシェルの PATH が参照できません。uvx と pipx を使えば、インストールが自動的に分離されるため、これらの問題をすべて回避できます。}

コードに取り組む場合は、代わりにソースからインストールしてください。

git clone https://github.com/mbk-dev/okama-mcp
cd okama-mcp
uv python install 3.14
uv sync --python 3.14 --all-groups

Planner 0.5.0 が公開されるまでは、tool.uv.sources が変更不可能な開発用コンパニオンを固定します。リリースゲートでは uv sync --all-groups --no-sources を使用し、依存関係が公開済みであることを要求します。公開時にソースの差し替えは行いません。 公開済みの組み合わせで受け入れ確認に合格した後、開発用の固定を削除してください。

実行

# stdio — for Claude Desktop, Claude Code, Cursor (local IPC)
okama-mcp stdio

# streamable HTTP — for self-hosting on your own server
okama-mcp http --host 127.0.0.1 --port 8765

ソースチェックアウトから実行する場合は、各コマンドの先頭に uv run を付けてください。 各ワークツリーには独自の .venv があり、test グループと dev グループはデフォルトでインストールされます。 uv.lock はローカルで生成され、コミットされないため、新しいチェックアウトでは互換性のあるバージョンがそれぞれ個別に解決されます。Orca はエージェントを起動する前に orca.yaml のブートストラップを実行します。ソースの MCP 設定では、セットアップ後に uv run --no-sync が使われます。

クライアントを接続する

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "okama": {
      "command": "uvx",
      "args": ["okama-mcp", "stdio"]
    }
  }
}

Claude Desktop を再起動すると、ツールメニューにサーバーが表示されます。

Claude Code

すべてのプロジェクトでサーバーを利用できるようにするには（どのディレクトリからでも使用できます）：

claude mcp add --scope user okama -- uvx okama-mcp stdio

ソースチェックアウトから実行する開発者は、代わりにプロジェクトのルートから claude mcp add okama -- uv run okama-mcp stdio を実行できます。

または、プロジェクトのルートに .mcp.json をコミットすると、チーム全体で利用できます。

{
  "mcpServers": {
    "okama": {
      "command": "uvx",
      "args": ["okama-mcp", "stdio"]
    }
  }
}

Cursor

プロジェクト内の .cursor/mcp.json にサーバーを追加します（グローバルに設定する場合は ~/.cursor/mcp.json に追加します）。

{
  "mcpServers": {
    "okama": {
      "command": "uvx",
      "args": ["okama-mcp", "stdio"]
    }
  }
}

Codex（CLI とデスクトップ）

次のコマンドでサーバーを追加します。

codex mcp add okama -- uvx okama-mcp stdio

または、~/.codex/config.toml（信頼済みプロジェクトでは、プロジェクト単位の .codex/config.toml）で宣言します。

[mcp_servers.okama]
command = "uvx"
args = ["okama-mcp", "stdio"]

Codex CLI、デスクトップアプリ、IDE 拡張機能はこの設定を共有します。一度設定すれば、3 つすべてで動作します。

セルフホスティング（ストリーミング可能な HTTP）

okama-mcp を自分のサーバーで実行し、MCP クライアント間で共有します。

okama-mcp http --host 127.0.0.1 --port 8765 --path /mcp

（ソースから実行する場合：uv run okama-mcp http ...）

次に、MCP クライアントの接続先を http://<your-server>:8765/mcp に設定します。本番環境では nginx と TLS を前段に配置してください。すぐに利用できる設定例は deploy/ にあります。

• deploy/systemd/okama-mcp.service — systemd ユニット（セキュリティ強化済み、専用ユーザーで実行）
• deploy/nginx/self-hosted.conf — nginx 仮想ホスト：TLS、/mcp の SSE 対応プロキシ

このサーバーは設計上、公開されています。無料で実行でき、登録も不要です。インスタンスを公開してはならない場合は、nginx レベルでアクセスを制限してください（許可リスト、VPN、または HTTP 基本認証）。

ツールカタログ

複数段階の金融プラン（SPY/AGG ポートフォリオに毎月 $1,000 を 20 年間積み立て、その後、インフレ連動で毎月 $6,000 を 25 年間取り崩す）、モンテカルロ退職予測（金 30%／不動産 70% のポートフォリオから、インフレ連動で毎月 $1,000 を 25 年間取り崩す）、および SPY/BND/GLD の効率的フロンティア：

金融ツールはステートレスです。呼び出しごとに、ポートフォリオの仕様全体を渡してください。 任意のローカルクライアントツールでは、安定したレジストリコードと、データベース単位で永続化されるアクセスモードを使用します。 クライアントの作成は冪等ではありません。作成結果が不明確で再試行する前に、レジストリを確認してください。 サーバーはコストの高い okama オブジェクト（Portfolio、EfficientFrontier）をコンテンツハッシュでキャッシュするため、同じ仕様で繰り返し呼び出すと高速です。

ネストされたポートフォリオ。 資産のリストを受け付ける箇所（PortfolioSpec／FrontierSpec の assets フィールド、または比較ツールの portfolios 引数）では、各項目にティッカー文字列またはネストされたポートフォリオオブジェクト（同じ仕様形式）を指定できます。これにより、ポートフォリオ全体を単一の構成要素として扱えます。たとえば、60/40 ポートフォリオと金を比較したり、サブポートフォリオを効率的フロンティアに含めたりできます。

検索とメタデータ

ツール	用途
search_assets(query="", namespace?, asset_type?, oldest_first?, limit=50, offset=0)	名前／ローカル名／ティッカー／ISINで検索します。完全一致する識別子と名前が最初に表示されます。has_more が true の場合は、next_offset を使って続けてください。okama のタイプで絞り込み、first_date で並べ替えます。たとえば、namespace="MOEX", asset_type="ETF", oldest_first=true, limit=5 を指定すると、MOEX 上場の BPIF のうち最も古い5件が見つかります。
list_namespaces(kind="all"|"assets"|"macro")	名前空間の説明と usage（資産／マクロの分類、資産リターンへの対応状況、利用可能な MCP ツール）を表示します。
get_asset_info(symbol)	1つのシンボルのメタデータ（名称、国、通貨、タイプ、日付範囲）を取得します。

単一資産と比較

ツール	用途
get_asset_history(symbol, kind, first_date?, last_date?)	1つの資産の時系列データを取得します。kind ∈ {close_monthly, close_daily, adj_close, ror, dividends}。
compare_assets(symbols, ccy, ..., portfolios?, rf_return?, t_return?)	資産ごとの統計を横並びで表示します（describe() テーブル：CAGR、リスク、期間別のドローダウン）。資産ごとのシャープレシオとソルティノレシオも表示します。
get_correlations(symbols, ccy, ..., portfolios?)	月次リターンの相関行列を取得します。
get_rolling_risk(symbols, ccy, window_months=12, ..., portfolios?)	資産ごとのローリング年率リスクを取得します。
get_asset_returns(symbols, ccy, ..., portfolios?, period?, real=False)	資産ごとのリターン指標を取得します。CAGR、累積リターン、平均／実質平均リターン、月次幾何平均、年間リターンのテーブルが含まれます。inflation=False の場合、名目指標は引き続き利用できますが、real_mean_return は null になります。real=True を指定するには inflation=True が必要です。
get_rolling_returns(symbols, ccy, window_months=12, real=False, ..., portfolios?)	資産ごとのローリング CAGR とローリング累積リターンを取得します。
get_benchmark_metrics(benchmark, symbols, ccy, ..., portfolios?, rolling_window?)	ベンチマーク／インデックスに対する各資産のベータ、相関、年率トラッキング差、トラッキングエラーを取得します。
get_dividend_info(symbols, ccy, ...)	資産ごとの直近12か月の配当利回り、過去5年の平均利回り、配当支払い／増配の連続期間を取得します。

ポートフォリオのバックテスト

ツール	用途
analyze_portfolio(portfolio, rf_return=0, t_return=0)	主要指標（CAGR、年平均リターン／リスク、シャープレシオ、ソルティノレシオ）と、PortfolioSpec の完全な describe() を取得します。
get_portfolio_drawdowns(portfolio)	ドローダウンの時系列と、最大ドローダウン／回復期間を取得します。
get_portfolio_var_cvar(portfolio, time_frame=12, level=1)	ヒストリカル VaR と CVaR を取得します。
get_portfolio_wealth_index(portfolio, full=False)	資産指数の時系列（1000からの累積成長）を取得します。
get_rolling_cagr(portfolio, window_months=12, real=False)	ローリング CAGR の時系列を取得します（インフレ調整を適用可能）。
get_cagr_probability(portfolio, years, cagr_target)	N年間の期間において、CAGRが目標値（損失など）を下回る過去の確率を取得します。

モンテカルロ DCF

ツール	用途
monte_carlo_forecast(portfolio, mc, cashflow)	5つのキャッシュフロー戦略（indexation、percentage、time_series、vanguard、cut_if_drawdown）のいずれかを使って将来をシミュレーションします。資産額のパーセンタイル帯、最終資産額の統計、生存指標を返します。金額加重 IRR の分布（パーセンタイル＋平均）も含まれます。
get_portfolio_irr(portfolio, cashflow)	拠出／引き出し計画に対する、過去の金額加重リターン（IRR）を取得します。
find_the_largest_withdrawals_size(portfolio, mc, cashflow, goal, ...)	goal（実質購買力の維持、名目残高の維持、または N 年間の生存）を達成する、持続可能な最大引き出し額をモンテカルロ法で求めます。
get_monte_carlo_cash_flow(portfolio, mc, cashflow, discounting?)	将来のキャッシュフローのモンテカルロ分布を時系列で取得します（パーセンタイル帯）。

mc 引数では distribution_parameters を指定して、当てはめた分布を上書きできます（例：Student-t 分布の df を固定）。以下の MCSpec の形式を参照してください。

財務計画（複数ステージ）

計画は、各ステージがそれぞれ独自のポートフォリオ、期間、キャッシュフロー方式を持つ、順序付けられた一連のステージです。シナリオは連鎖します。モンテカルロシナリオがあるステージを終えるときの残高が、次のステージの開始残高になります。そのため、退職ステージの資金は、蓄積ステージで同じシナリオ内に生じた結果によって賄われます。蓄積ステージのパーセンタイル値によって賄われるわけではありません。期間の途中でポートフォリオまたは拠出／引き出し方式が変わる場合は、monte_carlo_forecast ではなく、これらを使用してください。

ツール	目的
finplan_forecast(plan, success_threshold=0)	計画全体のモンテカルロ予測です。資産額のパーセンタイル帯、最終資産額の統計値、資産維持指標、success_threshold を上回って終了するシナリオの割合、各ステージ境界での残高分布、IRR 分布を取得できます。
finplan_backtest(plan, discounting?, first_date?)	実際の過去データを用いて同じ計画を再現する、グライドパスのバックテストです。各ステージのポートフォリオが対象とする期間は、計画期間以上である必要があります。

分布の診断

ツール	目的
get_distribution_fit(portfolio, mc)	リターン分布の適合度を確認します。適合パラメーター、Jarque-Bera、Kolmogorov-Smirnov 検定（選択した分布とすべての分布）、バックテスト誤差（理論値と経験値の平均／VaR／CVaR）を取得できます。
get_return_moments(portfolio, mc, rolling_window?)	歪度と尖度の時系列です。期間を指定しない場合は累積、期間（月数）を指定した場合はローリングで算出します。
optimize_students_df(portfolio, mc, var_level?)	経験的な VaR／CVaR に最もよく適合する Student-t 分布の自由度を求めます。
get_cagr_distribution(portfolio, mc, percentiles?, score?)	各パーセンタイルでのシミュレーションによる CAGR と、CAGR が score 以下になる確率（例：score=0 → 損失が発生する確率）を取得できます。

DCF（過去のキャッシュフロー分析）

ツール	目的
get_dcf_wealth_index(portfolio, cashflow, discounting?, include_negative_values?, discount_rate?)	キャッシュフロー計画に基づく過去の資産指数です（名目 FV または割引後 PV）。
get_dcf_cash_flow_ts(portfolio, cashflow, discounting?, remove_if_wealth_index_negative?, discount_rate?)	過去の拠出／引き出し時系列です（FV または PV）。
get_dcf_wealth_with_assets(portfolio, cashflow)	ポートフォリオと各構成資産の過去の資産指数です。
get_survival_period(portfolio, cashflow, threshold?, discount_rate?)	過去の資産寿命です。資産維持期間（年）と枯渇日を取得できます。
get_initial_investment_values(portfolio, cashflow, discount_rate?)	初期投資の現在価値（PV）と将来価値（FV）です。

効率的フロンティア

ツール	目的
build_efficient_frontier(frontier)	EF の全ポイント表です（リスク／平均リターン／CAGR と、資産ごとのウェイト）。
get_tangency_portfolio(frontier, rf_return, rate_of_return)	EF 上でシャープレシオが最大のポートフォリオです。
get_min_variance_portfolio(frontier)	グローバル最小分散ポートフォリオです。
get_most_diversified_portfolio(frontier, target_return?)	EF 上で分散比率が最大となる、最も分散されたポートフォリオです。

マクロ

ツール	目的
get_inflation(currency, first_date?, last_date?, include_cumulative?, include_rolling?, include_describe?)	通貨（USD、EUR、RUB など）のインフレ率系列です。オプションで累積インフレ率、12 か月ローリングインフレ率、describe() テーブルを取得できます。
get_central_bank_rate(country, first_date?, last_date?, frequency="monthly"|"daily", include_describe?)	中央銀行の政策金利です（US→US_EFFR、EU／ECB→EU_MRO、RUS→RUS_CBR、UK／GB→UK_BR、ISR→ISR_IR、CN／CHN→CHN_LPR1、または完全なシンボル）。月次または日次の系列を取得できます。オプションで describe() テーブルも取得できます。
get_indicator(symbol, first_date?, last_date?, include_describe?)	RATIO 名前空間のマクロ指標です（例：USA_CAPE10.RATIO）。国コードのみを指定すると、その国の CAPE10 がデフォルトで使用されます。

チャート

各ツールは PNG（デフォルトは 1500×900）をレンダリングし、MCP の画像コンテンツとして返します。Claude Desktop などのクライアントでは、インラインで表示されます。すべてのチャートツールでは、カスタムサイズやアスペクト比を指定するための省略可能な width / height（ピクセル単位、300～4000）と、省略可能な save_path も指定できます。指定すると、チャートはそのファイルにも書き込まれ、パスが返されます。UI で MCP の画像をレンダリングしないクライアント（例：Claude Code のターミナル）では、save_path を使用します。「/tmp/chart.png に保存したチャート」を依頼し、ファイル参照を開いてください。注：セルフホスト可能な（streamable-http）デプロイでは、save_path はクライアントのマシンではなく、サーバーのファイルシステムに書き込まれます。

ツール	チャート
plot_wealth_index(portfolio)	ポートフォリオの富指数（＋インフレ率の線）。
plot_drawdowns(portfolio)	時間経過に伴うドローダウンの深さ。
plot_monte_carlo(portfolio, mc, cashflow)	モンテカルロ予測ファン（パーセンタイル帯）。
plot_finplan_forecast(plan)	財務計画の予測ファン：破線のステージ境界とステージラベル付きのパーセンタイル帯。
plot_irr_distribution(portfolio, mc, cashflow)	モンテカルロシナリオ全体の IRR のヒストグラム（パーセンタイルマーカー付き）。
plot_qq(portfolio, mc)	適合分布（norm/lognorm/t）に対する過去のリターンの Q-Q プロット。
plot_hist_fit(portfolio, mc, bins?)	過去のリターンのヒストグラムと、重ねて表示した適合分布の PDF。
plot_efficient_frontier(frontier)	個別資産の点を含む EF 曲線。
plot_transition_map(frontier, x_axe="risk")	推移マップ：効率的フロンティアに沿った資産配分（x 軸＝リスクまたは CAGR）。
plot_assets(symbols, ccy, ..., portfolios?)	個別資産の富指数の比較。
plot_macro(symbols, first_date?, last_date?, frequency="monthly"|"daily")	インフレ率／中央銀行金利／CAPE10 系列の折れ線グラフ。複数のシンボルを重ねて表示します（例：["USA_CAPE10.RATIO", "EUR_CAPE10.RATIO"]）。frequency='daily' は .RATE シンボルでのみ有効です。

シンボルの検索とツールの選択

まず list_namespaces() を使います。元の namespaces の説明マッピングは保持され、各名前空間でサポートされる内容は usage で確認できます。指数カタログを参照するには search_assets(namespace="INDX") を、暗号通貨を検索するには search_assets(query="bitcoin", namespace="CC") を使います。検索結果には namespace と supports_asset_returns（不明な場合は null）が含まれます。

検索では大文字と小文字が区別されません。シンボル／ティッカー／ISIN の完全一致が最初にランク付けされ、続いて名前の完全一致、前方一致、その他の一致の順になります。範囲を指定したクエリでは、句読点も文字どおりに照合されます。oldest_first=true の場合は、日付順が優先されます。同順位の場合はシンボル順で並びます。結果はページ分割の前に並べ替えられます。has_more=false になるまで、同じクエリとフィルターを使用して offset=next_offset を指定し、繰り返し呼び出してください。count はフィルターに一致するすべての結果を示します。truncated は、複数ページにわたる結果の最終ページも含め、現在のページが結果全体ではないことを示します。ページは現在のカタログを反映するため、呼び出しの間にデータが更新されると、ページの境界が移動する場合があります。

RATE、INFL、RATIO はマクロ経済系列です。それぞれ get_central_bank_rate、get_inflation、get_indicator を使って、値とメタデータを取得してください。たとえば、RUS_RUB.RATE は預金金利を表す一方、OKID.INDX は投資リターン指数を表します。これらは異なる入力です。資産ツールにマクロシンボルを指定すると、適切な次の呼び出しを案内してエラーになります。指数に置き換えられることはありません。リターンを比較する前に、対応する指数を個別に確認してください。上流の名前空間のうち、サポートが実装されていないものには、MCP のルートは公開されません。

スキーマの形状

複雑なツールは、MCP の tools/list に完全な Pydantic 生成の入力スキーマが記載された JSON オブジェクトを受け付けます。ネストされたフィールド、必須値、制約、デフォルト値、キャッシュフローのバリエーションをクライアントで確認できます。定義は src/okama_mcp/schemas.py にあります。主な形状は次のとおりです。

// PortfolioSpec
{
  "assets":   ["GLD.US", "VNQ.US"],  // each entry: a ticker OR a nested PortfolioSpec
  "weights":  [0.3, 0.7],            // optional, must sum to 1.0
  "ccy":      "USD",
  "first_date": "2010-01",
  "last_date":  "2024-12",
  "rebalancing_strategy": {            // mirrors okama.Rebalance
    "period": "year",                  // month | quarter | half-year | year | none
    "abs_deviation": 0.05,             // optional, |actual - target| threshold, 0 < x <= 1
    "rel_deviation": 0.1               // optional, |actual / target - 1| threshold, > 0
  },
  "inflation": true
}

// MCSpec
{
  "distribution":  "norm",            // norm | lognorm | t
  "period_years":  25,
  "scenarios":     500,                // ≥ 1, no upper limit
  "percentiles":   [5, 50, 95],
  "random_seed":   42,                 // optional, for reproducibility
  "distribution_parameters": null      // optional; null = fit from history (MLE). Lengths: norm [mu, sigma]; lognorm/t [shape|df, loc, scale]. Any element null = fit that one (e.g. [4, null, null])
}

// CashflowSpec — discriminated by `type`
{ "type": "indexation",       "initial_investment": 1000000, "frequency": "month", "amount": -1000, "indexation": "inflation" }
{ "type": "percentage",       "initial_investment": 1000000, "frequency": "year",  "percentage": -0.04 }
{ "type": "time_series",      "initial_investment": 100000,  "events":    { "2030-06": -50000 }, "time_series_discounted_values": false }
{ "type": "vanguard",         "initial_investment": 1000000, "percentage": -0.04, "floor_ceiling": [-0.025, 0.05], "indexation": "inflation" }
{ "type": "cut_if_drawdown",  "initial_investment": 1000000, "frequency": "year",  "amount": -60000, "indexation": "inflation",
  "crash_threshold_reduction": [[0.2, 0.4], [0.5, 1.0]] }

// FinPlanSpec — a plan is a sequence of stages, chained per scenario
{
  "stages": [
    { "portfolio": { "assets": ["SPY.US", "AGG.US"], "weights": [0.7, 0.3] },
      "period_years": 20, "name": "accumulation",
      "cashflow": { "type": "indexation", "initial_investment": 100000, "frequency": "year", "amount": 12000, "indexation": 0.03 } },
    { "portfolio": { "assets": ["SPY.US", "AGG.US"], "weights": [0.3, 0.7] },
      "period_years": 25, "name": "retirement",
      "distribution": "t", "distribution_parameters": [5, null, null],
      "cashflow": { "type": "percentage", "initial_investment": 100000, "frequency": "year", "percentage": -0.04 } }
  ],
  "initial_investment": 100000,       // balance the first stage starts with
  "discount_rate": null,               // optional; null lets okama use inflation
  "scenarios": 500,
  "random_seed": 42,                   // optional
  "percentiles": [10, 50, 90],
  "name": "retirement plan"
}

// FrontierSpec
{
  "assets":   ["SPY.US", "BND.US", "GLD.US"],
  "ccy":      "USD",
  "bounds":   [[0.0, 0.7], [0.1, 1.0], [0.0, 0.3]],   // optional
  "n_points": 20,
  "rebalancing_strategy": { "period": "year" },
  "inflation": false
}

// Nesting — a portfolio used as a single component (works in PortfolioSpec /
// FrontierSpec `assets`, and the `portfolios` argument of the comparison tools):
{
  "assets": [
    "GLD.US",
    { "assets": ["SPY.US", "AGG.US"], "weights": [0.6, 0.4], "symbol": "bench6040.PF" }
  ],
  "weights": [0.3, 0.7]              // one weight per top-level entry
}

開発

このプロジェクトでは TDD（AGENTS.mdを参照）を採用しています。コードを変更するたびに、次を実行してください。

uv run pytest -q
uv run ruff check .

ライブ API 統合テスト（api.okama.ioにアクセスします）を実行するには、次を実行してください。

uv run pytest -m integration

プロジェクト構成

src/okama_mcp/
├── server.py          # FastMCP instance + registration entry point
├── transport.py       # CLI: `okama-mcp stdio | http`
├── schemas.py         # PortfolioSpec, MCSpec, CashflowSpec, FrontierSpec, FinPlanSpec
├── cache.py           # TTL+LRU cache keyed by sha256 of canonical spec
├── serialization.py   # pandas → JSON-safe with smart truncation
├── errors.py          # Translate okama exceptions to actionable MCP errors
└── tools/
    ├── search.py, asset.py, asset_list.py
    ├── portfolio.py, monte_carlo.py, finplan.py
    ├── frontier.py, macro.py
    └── plots.py

ライセンス

MIT — okama 自体と同じライセンスです。

Planner とローカルクライアントのワークフロー

Planner ツールを使用するには、okama_planner.aiを提供するコンパニオンが必要です。ローカルクライアントモードでは、さらにPlannerClientAccessが必要です。互換性のあるバージョンに固定されたソースはuv syncで解決されます。必要な API がない場合は、安全側に倒して失敗します。設定済みのローカル stdio では、17 個のクライアントツールと Excel エクスポート（合計 70 個のツール）が利用できます。HTTP にはクライアントツールやローカルレポートツールはありません。

デフォルトのanonymousモードでは仮名が返され、クライアントデータへのすべての永続的な書き込みが拒否されます。個人情報は Planner で管理します。client_data_mode_setをmode="personal_data"で呼び出すと、完全なレコードの読み取り、クライアントの作成、更新、削除のほか、Planner の API を介した居住メモやプランのバージョンの保存が可能になります。匿名アクセスに戻すには、mode="anonymous"で呼び出してください。client_data_mode_getでは保存済みのモードを確認できます。このモードは同じデータベースを使用する接続間で共有され、再起動後も保持されます。

削除すると、選択したクライアントに関連付けられた Planner のレコードも削除されます。部分更新では指定されていないフィールドが保持されます。Planner が許可している場合、オプションのフィールドに明示的な null を指定すると、そのフィールドがクリアされます。予測とレポートは、どちらのモードでも匿名のままです。エラーには、個人情報、データベースの詳細、ファイルシステムのパスを含まない固定メッセージが使用されます。 従来の--allow-personal-dataフラグは、保存済みの設定がない場合に初期値を設定するだけで、MCP を介して明示的に保存されたモードを上書きすることはありません。ミーティングと上限付きの履歴ページにも同じアクセス方針が適用されます。以前パッケージに含まれていたインテークスキルは廃止されています。 設定とツールの仕様および言語の動作を参照してください。

okama ファミリーを探索する

投資とファイナンシャルプランニングのためのツールです。

プロジェクト	できること
okama.io	インタラクティブなウェブツールでポートフォリオを探索できます。
okama	Python で投資とポートフォリオを分析できます。
okama Data API	過去の市場データや経済データにアクセスできます。
okama-macro	インフレ率や中央銀行金利の時系列データを扱えます。
okama Planner	ファイナンシャルプランを作成し、クライアントのプランニング履歴を管理できます。

okama コミュニティに参加 →

質問したり、例を共有したり、ファイナンシャルプランニングについて話し合ったりできます。