foro
Build an MCP server locally, then know it will run the same anywhere.
foro is a small CLI and runtime shim for FastMCP
servers. It scaffolds a project, checks it, runs it under the same conditions a
container will, and proves a running server actually speaks MCP.
uvx foro init my-server && cd my-server
uvx foro dev
✓ would pass foro.sh's health check (port 8000)
Tools: add
Press Ctrl+C to stop.
Why
A server that works under mcp dev can still fail in a container: stdio
instead of streamable HTTP, bound to 127.0.0.1 instead of 0.0.0.0, a
hardcoded port, a secret read with a bare KeyError. Every one of those
surfaces as a health check that times out with no useful output.
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, 0.0.0.0, $PORT
foro.run() is duck-typed over any FastMCP-shaped server, and foro.secret()
raises an error that says where to set the missing value. The runtime has no
dependencies of its own, so a container installing foro doesn't pull in CLI
tooling it never runs.
CLI
| Command | What it does |
|---|
foro init [name] | Scaffold a project, or record settings in an existing pyproject.toml |
foro check [path] | Validate a repo against the deploy contract |
foro dev [path] | Run the server the way a container will, and report whether it passes |
foro verify <url> | Open a session against a deployed URL and list its tools |
foro auth | login, status, logout, token for foro.sh |
foro deploy [path] | Ship the directory to foro.sh and stream the build |
foro logs [path] | Read runtime, build or deploy logs (-f to follow, --contains to search, --summary to digest) |
foro projects | List, show or create projects, and turn auto-deploy on or off |
foro deployments | List deployments or show one; foro rollback and foro cancel act on them |
foro workspace | List, switch, create or rename workspaces |
foro templates / foro repos | What a new project can start from |
foro metrics / usage / sessions / incidents | How a deployed server is used and how it is doing |
foro scan / readiness / connect | Dependency CVEs, store-listing checks, and how to add the server to a client |
init, check and dev are local and need no account.
There is no foro-specific manifest. Config comes from pyproject.toml or
package.json, with an optional [tool.foro] table for what those files
can't express. See packages/python/README.md
for the full reference.
Claude Code plugin
/plugin marketplace add foro-sh/foro
/plugin install foro
Adds /foro:create-foro-project, /foro:add-foro-to-existing-server,
/foro:deploy-to-foro, /foro:debug-a-foro-deploy, /foro:design-mcp-tools
and /foro:wrap-an-http-api, plus a docs MCP server.
There's a Codex counterpart and a Cursor counterpart with the same skills.
Deploying
foro dev passing means the server satisfies the contract that
foro.sh builds against. foro auth login && foro deploy
uploads the working tree and streams the build to a live URL; a project linked
to a GitHub repo builds from its branch instead. Nothing here is locked to that platform —
foro.run() is a normal streamable-HTTP server on $PORT.
Packages
Contributing
Issues and PRs welcome. Commit messages follow
Conventional Commits — commitlint
enforces it on PRs, and release-please uses it to cut the changelog. Merge
feature PRs freely; a Release PR accumulates them and publishes when you
merge it.
npm install
cd packages/python && uv sync && uv run pytest
License
MIT
