foro (Python)

The Python SDK and CLI for foro.sh — the fastest path from "I want to build an MCP server" to a deployed https://<slug>.foro.sh URL.

• Quickstart
• CLI
• Runtime
• foro.yaml reference
• Example
• Develop this package

Quickstart

uvx foro init my-server && cd my-server
uvx foro dev

foro init scaffolds a working FastMCP server plus a foro.yaml; foro dev runs it exactly as foro.sh will and confirms it would pass the platform's health check. Once it looks good:

git init && git add -A && git commit -m "init" && gh repo create --push

Then, on the foro.sh dashboard: sign in with GitHub, pick the repo, add any secrets your tools need, and deploy.

CLI

Install once with uv tool install foro, or run ad-hoc with uvx foro ... — no need to add it to your project's own dependencies.

foro check mirrors the platform's own validation rule for rule, so a repo it passes will deploy and one it flags will not — the same reason code, surfaced locally instead of as a 60-second health-check timeout.

foro verify applies foro dev's standard to a deployed server: a URL that answers HTTP is not the same as one serving MCP, and a green deploy only means the container passed a TCP probe. It runs the same handshake foro dev does — initialize, then tools/list — and exits non-zero when that fails, so a script or a CI step can branch on it.

$ foro verify https://swift-harbor-a3f2.foro.sh
✓ https://swift-harbor-a3f2.foro.sh/mcp is serving MCP
Tools: get_forecast, list_cities

The /mcp path is appended when you leave it off, so the URL foro deploy printed works as-is.

Runtime

One import, used from your server's entrypoint:

from fastmcp import FastMCP
import foro

mcp = FastMCP("my-server")

@mcp.tool
def add(a: int, b: int) -> int:
    return a + b

if __name__ == "__main__":
    foro.run(mcp)  # streamable HTTP, host 0.0.0.0, port $MCP_PORT - identical locally and deployed

Bare foro (what a deployed container installs — no [cli] extra) stays dependency-free, so a deployed container never pulls in CLI tooling it doesn't use.

foro.yaml reference

Every deployable repo carries one, at its root:

name: my-server          # required, ^[a-z0-9-]{3,48}$ - display name only, not the URL slug
entrypoint: server.py    # required, relative path, run as `uv run <entrypoint>`
build_path: .            # optional, default "." - dir holding pyproject.toml + uv.lock
python_version: "3.12"   # optional, one of 3.11 / 3.12 / 3.13
port: 8000               # optional, default 8000 - the port your server must listen on

At runtime the container gets MCP_PORT (matching port above) and every project secret as its own env var. Public traffic arrives at https://<slug>.foro.sh, so your server must listen on 0.0.0.0:$MCP_PORT — which is exactly what foro.run() does for you.

Example

foro-sh/todo-mcp is a small stateful todo-list server built the way described above — every new foro.sh workspace gets a deployed copy of it to poke at before deploying anything of your own.

Develop this package

uv sync
uv run pytest