Okama MCP server

okama-mcp

<!-- mcp-name: io.github.mbk-dev/okama-mcp -->

MCP (Model Context Protocol) server that exposes the okama investment portfolio toolkit to AI assistants — Claude Desktop, Claude Code, Cursor, Codex, and any other MCP-compatible client.

With okama-mcp installed, you can ask an AI things like:

"Backtest a portfolio of 30% gold and 70% real estate over the last 15 years."

*"Run a Monte Carlo retirement forecast on that portfolio, withdrawing $1,000/month

indexed to inflation, over 25 years."*

"What's the tangency portfolio of SPY, BND, and GLD with a 3% risk-free rate?"

…and the AI uses the MCP tools to call okama directly — no Python code needed.

Built on FastMCP. Single codebase, two transports: stdio (for local clients) and streamable-http (for self-hosting). okama-mcp is free and open source — no hosted service, no registration; you run it yourself, locally or on your own server.

Install

Requires Python ≥ 3.11 (same floor as okama itself); okama ≥ 2.2.0 is installed automatically.

The easiest way — no clone, no venv — is uv or pipx:

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

Plain pip works too:

pip install okama-mcp

[!WARNING]

With pip, prefer a dedicated virtual environment: on most modern Linux distros the

system Python is marked externally managed (PEP 668), so pip install outside a venv

fails, and a shared environment risks dependency conflicts. In your MCP client config,

point command at the absolute path of the okama-mcp script inside the venv — GUI

clients don't see your shell PATH. uvx and pipx avoid all of this by isolating

the install automatically.

To work on the code, install from source instead:

git clone https://github.com/mbk-dev/okama-mcp
cd okama-mcp
poetry install

Run

# 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

When running from a source checkout, prefix each command with poetry run.

Connect a client

Claude Desktop

Edit ~/Library/Application Support/Claude/claudedesktopconfig.json (macOS) or %APPDATA%\Claude\claudedesktopconfig.json (Windows):

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

Restart Claude Desktop; the server appears in the tools menu.

Claude Code

To make the server available in every project (works from any directory):

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

Developers running from a source checkout can use claude mcp add okama -- poetry run okama-mcp stdio from the project root instead.

Or commit a .mcp.json at the project root so the whole team picks it up:

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

Cursor

Add the server to .cursor/mcp.json in your project (or ~/.cursor/mcp.json to make it global):

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

Codex (CLI & Desktop)

Add the server with one command:

Shortened. The full README is on GitHub.