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.
Ticker search
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.
Links
- Docs: https://www.folioforecast.com/developers
- OpenAPI spec: https://www.folioforecast.com/api/v1/openapi.yaml
- Dashboard / key management: https://www.folioforecast.com/hub?tab=settings
- Repository: https://github.com/shadow6-actual/V6_EODHD_POpt
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.