Modal MCP Server

Local, read-only Modal context for coding agents.

Modal MCP lets Codex, Claude Desktop, and other MCP clients inspect Modal apps, deployments, logs, containers, volumes, and sandboxes without granting mutation tools. It runs on your machine, uses your local Modal credentials, and exposes only read-oriented toolsets by default.

Why Use It

• Let agents inspect live Modal state instead of asking you to paste CLI output.
• Debug deployments, startup failures, and recent logs from the same chat.
• Keep Modal credentials local to your machine.
• Start with read-only behavior; destructive tools are disabled in v1.

Project Status

v1 is a local read-only beta.

Installation

One-liner (recommended)

# Pin to a release tag for supply-chain safety
curl -fsSL https://raw.githubusercontent.com/php-workx/modal-mcp/refs/tags/v0.1.0/install.sh -o install.sh
# Verify checksum against release notes, then execute:
sh install.sh

This script auto-detects your Python toolchain and installs modal-mcp with the best available method:

From source

git clone https://github.com/php-workx/modal-mcp.git
cd modal-mcp
uv sync --extra dev
uv run modal-mcp --help

PyPI

uv tool install modal-mcp
# or
pipx install modal-mcp
# or
pip install --user modal-mcp

Quickstart

Install from source and generate local server settings:

uv sync --extra dev
uv run modal-mcp setup --yes

modal-mcp setup --yes creates:

The generated .env intentionally does not contain Modal tokens or MODAL_ENVIRONMENT.

If this machine already has Modal CLI credentials in ~/.modal.toml, you can verify and start the server immediately:

uv run modal-mcp doctor --env-file .env
uv run modal-mcp run --env-file .env

Add Modal Credentials

For a quick local evaluation, existing Modal CLI credentials in ~/.modal.toml are used automatically. modal-mcp doctor warns when it finds them because they often belong to a personal editor or admin account.

For regular use, create a dedicated Modal service-user token with Viewer access and store it in files. Replace the placeholder values before running the diagnostic or server commands:

mkdir -p .secrets
printf '%s' '<modal-token-id>'     > .secrets/modal-token-id
printf '%s' '<modal-token-secret>' > .secrets/modal-token-secret
chmod 600 .secrets/*
printf '\nMODAL_TOKEN_ID_FILE=%s/.secrets/modal-token-id\n' "$PWD" >> .env
printf 'MODAL_TOKEN_SECRET_FILE=%s/.secrets/modal-token-secret\n' "$PWD" >> .env

Run the diagnostics again after adding credentials:

uv run modal-mcp doctor --env-file .env
uv run modal-mcp run --env-file .env

What Agents Can Ask

Try prompts like these after connecting your MCP client:

• "Which Modal workspaces and environments can this token see?"
• "List the apps in the current environment and summarize deployment status."
• "Show recent logs for this app and group likely startup failures."
• "Compare these two deployment versions and tell me what changed."
• "List running sandboxes and containers so I can spot stale resources."
• "Inspect this volume path and read a small text file from it."

See docs/examples.md for longer workflows.

Toolsets

The change and expert toolsets are registered only as disabled stubs so policy code can block them consistently. They are hidden from default tools/list.

Full catalog: docs/tools.md.

Connect An Agent

Codex CLI

Codex launches modal-mcp as a subprocess over stdio:

uv run modal-mcp setup --install codex --env-file "$PWD/.env" --dry-run
uv run modal-mcp setup --install codex --env-file "$PWD/.env" --yes

Claude Desktop

Claude Desktop connects to a running local server:

uv run modal-mcp run --env-file "$PWD/.env"
uv run modal-mcp setup --install claude --dry-run
uv run modal-mcp setup --install claude --yes

Other MCP Clients

Point Streamable HTTP clients at:

http://127.0.0.1:8765/mcp

For clients that still expect SSE:

http://127.0.0.1:8765/mcp/sse

More details: docs/clients.md.

Safety Model

• Local by default: the server binds to 127.0.0.1:8765 unless configured otherwise.
• Read-only by default: MODAL_MCP_READ_ONLY=true.
• Toolsets are allowlisted by MODAL_MCP_ENABLED_TOOLSETS.
• Origin and Host allowlists run before MCP request handling.
• Known secrets are redacted before JSON responses and audit logs leave the server.
• Raw Modal tokens should not be placed in .env; prefer file-backed secrets.

Volume text, logs, and sandbox stdio can still contain application-sensitive data. Use a non-production workspace or a dedicated Viewer-scoped service user when evaluating the server.

Security details: docs/threat-model.md.

Configuration

Required for self-hosted startup:

Recommended defaults:

MODAL_MCP_READ_ONLY=true
MODAL_MCP_ENABLED_TOOLSETS=discovery,apps,containers,logs,volumes,sandboxes
MODAL_MCP_AUDIT_LOG=stdout
MODAL_MCP_HTTP_BIND=127.0.0.1:8765

Full deployment guide: docs/self-hosting.md.

Troubleshooting

Start with:

uv run modal-mcp doctor --env-file .env

doctor checks package imports, .env, signing keys, allowed origins, read-only settings, enabled toolsets, Modal credential source, Modal SDK auth, and Modal CLI availability.

Exit codes:

Common fixes: docs/troubleshooting.md.

Development

Install local command runners:

brew install just shellcheck actionlint betterleaks semgrep

Run the local gates:

just setup
just pre-commit
just pre-push
just check
just uv-audit

Live Modal tests are opt-in and should use non-production credentials:

MODAL_MCP_LIVE=1 MODAL_ENVIRONMENT=dev uv run pytest tests/integration/live -q

Documentation

• Tool catalog
• Example agent workflows
• Client setup
• Troubleshooting
• Architecture
• Self-hosting guide
• Threat model
• Security policy
• Contributing guide
• Changelog