Skip to main content

folioforecast

Python SDK and MCP server for FolioForecast — programmatic portfolio optimization for AI agents, robo-advisors, and fintech apps.

One API call to optimize, search, or stress-test any portfolio. Same engine that powers the FolioForecast web app, wrapped in a clean Python interface and a drop-in Model Context Protocol server for Claude Desktop, Claude Code, Cursor, and Windsurf.

Install

pip install folioforecast

For the MCP server:

pip install "folioforecast[mcp]"

Python 3.10+.

Get an API key

Sign up at folioforecast.com and create a key. Production keys start with ff_live_; sandbox keys start with ff_test_ (no billing).

SDK quick start

import folioforecast as ff

client = ff.Client(api_key="ff_live_...")

result = client.optimize(
    tickers=["AAPL.US", "MSFT.US", "GOOGL.US", "AMZN.US"],
    goal="max_sharpe",
)

print(result.weights)    # {'AAPL.US': 0.30, 'MSFT.US': 0.25, ...}
print(result.metrics)    # {'sharpe': 1.42, 'volatility': 0.18, ...}

All SDK methods are synchronous. Use it inside asyncio.to_thread(...) if you need to call it from an async context.

hits = client.search_tickers("apple", limit=5)
for h in hits:
    print(h.symbol, h.name, h.exchange)

Free — 0 compute units.

Stress test

result = client.stress_test(
    tickers=["SPY.US", "TLT.US", "GLD.US"],
    weights={"SPY.US": 0.6, "TLT.US": 0.3, "GLD.US": 0.1},
    scenarios=["2008_gfc", "covid_2020"],
)
print(result.scenarios)

Asset metadata

meta = client.asset_metadata(tickers=["AAPL.US", "AGG.US", "GLD.US"])
for m in meta:
    print(m.symbol, m.sector, m.asset_class)

Usage and billing

print(client.usage())   # current period compute units consumed / remaining
print(client.health())  # API status

Error handling

from folioforecast import AuthError, BillingError, RateLimitError, APIError

try:
    client.optimize(tickers=["AAPL.US"], goal="max_sharpe")
except AuthError:
    print("API key is missing or invalid")
except BillingError:
    print("Add a payment method at https://www.folioforecast.com/hub?tab=settings")
except RateLimitError as e:
    print(f"Slow down — retry after {e.retry_after}s")
except APIError as e:
    print(f"API error {e.status_code}: {e}")

Context-manager use

with ff.Client(api_key="ff_live_...") as client:
    result = client.optimize(tickers=["VOO.US", "AGG.US"], goal="min_volatility")

MCP server for Claude Desktop

The folioforecast[mcp] extra installs a full MCP server so Claude Desktop (and other MCP clients) can call the FolioForecast API directly.

1. Install

pip install "folioforecast[mcp]"

2. Configure Claude Desktop

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

{
  "mcpServers": {
    "folioforecast": {
      "command": "folioforecast-mcp",
      "env": {
        "FOLIOFORECAST_API_KEY": "ff_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You should see the FolioForecast tools appear in the attachment menu.

3. Try it

In a new Claude Desktop chat, ask:

Optimize a portfolio of AAPL, MSFT, GOOGL, and AMZN for maximum Sharpe ratio.

Claude will call optimize_portfolio and show you the weights and metrics.

Works in

Claude Desktop, Claude Code, Cursor, Windsurf, and any other MCP-capable client. Does not work in claude.ai web, the Claude mobile app, or claude.com — those surfaces do not load third-party MCP servers. For ChatGPT, use the pre-built FolioForecast Custom GPTs instead.

Tools exposed

Tool Description Cost
optimize_portfolio Run mean-variance optimization across 20 methods (Sharpe, min-vol, risk parity, Kelly, CVaR, etc.) 1–2 units
search_tickers Search 165,000+ tickers by symbol or name Free
stress_test Crisis scenario analysis (2008 GFC, COVID, etc.) 1 unit/scenario
get_asset_metadata Sector, industry, asset class, market cap 0.1 units/ticker

Parity note: this Python package mirrors the four portfolio tools in the Node MCP server at v1.0.0. Budget and retirement tools are rolling out in the next release.

Environment variables

Variable Required Description
FOLIOFORECAST_API_KEY Yes (for MCP server) Your API key
FOLIOFORECAST_API_URL No Override the base URL (default: https://www.folioforecast.com/api/v1)

The SDK accepts api_key as a constructor argument and falls back to the env var if omitted.

License

MIT — see LICENSE.


FolioForecast is a calculation engine. Your AI does the thinking — we do the math. Results are historical analysis, not predictions. Not financial advice.

Metadata

Release files for folioforecast 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for folioforecast 0.1.1
File Size Uploaded Provenance Actions
folioforecast-0.1.1.tar.gz 13.0 kB Without provenance Details for folioforecast-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for folioforecast 0.1.1
File Interpreter ABI Platform Actions
folioforecast-0.1.1-py3-none-any.whl Python 3 none any Details for folioforecast-0.1.1-py3-none-any.whl

Total release size: 28.9 kB

Release files / folioforecast-0.1.1.tar.gz

Download URL folioforecast-0.1.1.tar.gz
Size 13.0 kB
Tags Source
SHA-256 checksum
How to use checksums
2449b92daee88fd287950edc1d3e05b60bd14ad9e2ddf697b9bfb2fb6a577674
BLAKE2b-256 checksum
How to use checksums
86849d914bfa701792cbdf4856ca7f3f018a0e3d15e1165292f8261a72ffa18d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Release files / folioforecast-0.1.1-py3-none-any.whl

Download URL folioforecast-0.1.1-py3-none-any.whl
Size 15.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
72fb04140f5b2fbd5b327554ed278639babccf36d434f6cb466f00bd691788cb
BLAKE2b-256 checksum
How to use checksums
fa229be66b7aea624d77787824ebb2852eb1ef9ea933ebb8ea90a368ac3f6a12
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Security for folioforecast 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page