# okama-mcp

Connects the okama investment library to AI coding assistants for portfolio backtesting, Monte Carlo simulations, and efficient frontier charts.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5 repo stars
- Author: mbk-dev
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/mbk-dev/okama-mcp
- Updated: 2026-10-21
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/okama-mcp

## What it does

This server connects the okama toolkit and okama Planner directly to your AI client. It allows the assistant to search asset registries, evaluate historical returns, and model retirement scenarios. You do not need to write Python. The model handles calculations through direct tool calls.

Built on FastMCP, the project runs over local `stdio` or a streaming HTTP server. Financial computations stay stateless, meaning each request supplies the full asset structure. The server hashes inputs to cache heavy calculations like `Portfolio` or `EfficientFrontier`. It also accepts nested portfolios, treating an entire basket of securities as a single sub-asset.

Running the server requires Python 3.11 or newer. Excel reports and client registry tools stay disabled on remote HTTP endpoints, so you must run local `stdio` if you need spreadsheet exports.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add okama-mcp -- uvx okama-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from okama-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add okama-mcp -- uvx okama-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from okama-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "okama-mcp": {
            "command": "uvx",
            "args": [
                "okama-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from okama-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "okama-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "okama-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from okama-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add okama-mcp uvx okama-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from okama-mcp <command>

## When to use it
- run backtests on custom portfolio allocations against historical data
- generate Monte Carlo retirement simulations with inflation adjustments
- compute the efficient frontier for multiple assets and risk-free rates
- search securities by ticker, name, or ISIN code

## Example prompts
- Find the tangency portfolio for SPY, BND, and GLD assuming a 3% risk-free rate.
- Run a Monte Carlo forecast withdrawing 1,000 dollars monthly adjusted for inflation over 25 years.

## Similar
- [forward-risk](https://affpapa.org/en/nevibecode/skills/forward-risk.md) — skill · 766 installs
- [longbridge-portfolio](https://affpapa.org/en/nevibecode/skills/longbridge-portfolio.md) — skill · 4000 installs
- [asset-allocation](https://affpapa.org/en/nevibecode/skills/asset-allocation.md) — skill · 959 installs
- [portfolio-analytics](https://affpapa.org/en/nevibecode/skills/portfolio-analytics.md) — skill · 559 installs
- [Robinhood Portfolio Research](https://affpapa.org/en/nevibecode/mcp/robinhood-portfolio-research.md) — MCP server · ★ 41 repo stars
- [Canli Quant](https://affpapa.org/en/nevibecode/mcp/canli-quant.md) — MCP server · ★ 6 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
