{
  "markdown": "<!-- mcp-name: io.github.george-bobby/mcp-modal -->\n\n# MCP Modal Server\n\n[![mcp-modal MCP server](https://glama.ai/mcp/servers/george-bobby/mcp-modal/badges/card.svg)](https://glama.ai/mcp/servers/george-bobby/mcp-modal)\n\n[![PyPI](https://img.shields.io/pypi/v/mcp-modal.svg)](https://pypi.org/project/mcp-modal/)\n\nAn MCP server for managing [Modal](https://modal.com) — apps, containers, volumes, and secrets — and for deploying & running Modal apps directly from [Claude Code](https://docs.claude.com/en/docs/claude-code) and other MCP clients.\n\n\nEvery tool shells out to your local `modal` CLI, so it operates against whatever Modal profile and credentials are configured on your machine. There are no extra tokens to manage.\n\n## Installation\n\nThe server is published on PyPI as [`mcp-modal`](https://pypi.org/project/mcp-modal/). No manual install is needed — the recommended way to run it is with [`uvx`](https://docs.astral.sh/uv/), which fetches and launches it on demand. Just point your MCP client at the command below (see [Configuration](#configuration)).\n\n## Logging in to Modal\n\nThis server uses your local Modal credentials. If you haven't authenticated yet, run:\n\n```bash\nmodal setup\n```\n\nThis opens a browser to log in and stores a token in `~/.modal.toml`. Already logged in elsewhere? Check with `modal profile current`.\n\n## Configuration\n\nAdd the server to Claude Code with the `claude mcp` CLI:\n\n```bash\nclaude mcp add mcp-modal -- uvx mcp-modal@latest\n```\n\nOr add it to a `.mcp.json` file in your project root, which is the better option for a team\n— everyone who opens the repo gets the same configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-modal\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-modal@latest\"]\n    }\n  }\n}\n```\n\n### Why `@latest`, and when to pin instead\n\n`uvx` caches the environment it builds on the first run and **does not check PyPI again**:\n\n> \"uvx will use the latest available version of the requested tool on the first invocation.\n> After that, uvx will use the cached version of the tool unless a different version is\n> requested, the cache is pruned, or the cache is refreshed.\"\n> — [uv docs](https://docs.astral.sh/uv/concepts/tools/)\n\nSo a plain `uvx mcp-modal` means *latest at install time, frozen forever after* — restarting\nthe client or rebooting changes nothing, because the cache lives on disk. Different people\nend up on different versions depending on when they first ran it, with no warning.\n\n- **`mcp-modal@latest`** re-resolves on every launch, so a restart picks up new releases.\n  Costs one network round-trip at startup. Use it while the tool surface is still moving.\n- **`mcp-modal@0.3.0`** (an explicit version) is reproducible and upgrades become a\n  deliberate one-line change. Use it once you want stability, or for a wider audience.\n\nTo move a machine that is already stuck on an old cached build, switching it to either form\nabove is enough — requesting a version invalidates the cache. Otherwise\n`uv cache clean mcp-modal` forces a refresh.\n\n## Requirements\n\n- Python 3.11 or higher\n- [`uv`](https://docs.astral.sh/uv/) (provides `uvx`)\n- Modal CLI 1.5 or newer, configured with valid credentials (`modal setup`) — 1.5 is\n  where `modal billing summary`/`rates` landed and where the billing report switched to\n  snake_case columns; the cost tool reads both spellings but needs 1.5 for those two views\n- For Modal **deploy** and **run** support:\n  - The project being deployed/run must use `uv` for dependency management\n  - `modal` must be installed in that project's virtual environment\n\n## Security\n\nThis server shells out to your local `modal` CLI using whatever credentials are in\n`~/.modal.toml`. A few tools are powerful by design — if the MCP client driving the server\nis ever prompt-injected (for example by malicious text inside logs it fetched), these are\nthe escalation paths and should stay **behind your client's tool-approval prompts** rather\nthan being auto-approved:\n\n- **`deploy_modal_app` / `run_modal_app`** — execute arbitrary local Python on the host\n  (`modal deploy` imports the app file; `uv run` resolves and installs the target project's\n  dependencies).\n- **`modal_volume_files`** with `action=\"put\"` — can read any local file (e.g. `~/.ssh/id_rsa`,\n  `~/.modal.toml`) and upload it to a cloud volume (a data-exfiltration primitive).\n- **`modal_volume_files`** with `action=\"get\"` and `force=True` — can overwrite any local path\n  (e.g. `~/.zshrc` or a shell profile, a persistence primitive).\n- **`manage_modal_container`** with `action=\"exec\"` — runs arbitrary commands inside a\n  container, by design.\n\nEvery tool declares [MCP tool annotations](https://modelcontextprotocol.io/specification/server/tools#tool-annotations),\nso a client can distinguish the three read-only tools (`list_modal_resources`,\n`get_modal_logs`, `search_modal_logs`, all `readOnlyHint: true`) from the seven that change\nremote state (`destructiveHint: true`, except `run_modal_app`). Auto-approve the reads;\nkeep the writes behind a prompt.\n\n### Optional local-path allowlist\n\nTo contain the two filesystem-touching volume tools, set the\n`MCP_MODAL_ALLOWED_LOCAL_PATHS` environment variable to an\n[`os.pathsep`](https://docs.python.org/3/library/os.html#os.pathsep)-separated list of\ndirectories (`:` on macOS/Linux). When it is set, `modal_volume_files` is refused for any\nlocal path — `local_path` on `action=\"put\"`, the destination on `action=\"get\"` — unless the\nresolved path, after expanding `~` and collapsing `..`/symlinks, falls inside one of those\nroots. The download target `\"-\"` (return contents instead of writing a file) is exempt\nbecause nothing is written to disk.\n\nWhen the variable is **unset (the default) there is no restriction**, so existing setups are\nunaffected. Configure it in your MCP client, e.g.:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-modal\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-modal\"],\n      \"env\": { \"MCP_MODAL_ALLOWED_LOCAL_PATHS\": \"/Users/me/modal-workspace:/tmp/modal\" }\n    }\n  }\n}\n```\n\nAll tools also pass user-supplied names/paths after a `--` end-of-options separator, so a\nvalue beginning with `-` is always treated as data, never as a `modal` CLI flag. Secret\nvalues handed to `manage_modal_secret` are redacted from the echoed command, logs, and any\nerror output.\n\n## Supported Tools\n\n12 tools. Related operations are grouped behind an `action`/`resource` argument rather than\nsplit one-per-CLI-subcommand: every tool schema is loaded into the model's context for the\nwhole session, so a smaller surface leaves more room for your actual work (and gives the\nmodel fewer near-identical tools to choose between).\n\nTools that talk to environment-scoped resources take an optional `env` argument to target a\nspecific [Modal environment](https://modal.com/docs/guide/environments); if omitted, they\nuse the profile's default (or `MODAL_ENVIRONMENT`). The exception is `manage_modal_container`\nand container logs — a container ID is globally unique and the CLI accepts no environment\nthere.\n\n### Read-only\n\n1. **List Modal Resources** (`list_modal_resources`) — one lookup for the whole account.\n   - Parameters: `resource` (required), `name`, `path` (default `/`), `env`\n   - `resource` values:\n     | value | returns | `name` means |\n     | --- | --- | --- |\n     | `apps` | deployed/running/recently-stopped apps | — |\n     | `app_history` | one app's deployment versions (for rollback) | app name/ID |\n     | `containers` | running containers (`ta-...`) | app ID to filter by |\n     | `volumes` | named volumes | — |\n     | `volume_files` | files inside a volume (with `path`) | volume name |\n     | `secrets` | secret names (values are never exposed) | — |\n     | `environments` | valid `env` values for this workspace | — |\n     | `profile` | active profile + all profiles | — |\n   - `volume_files` sets `empty: true` with a message when a listing genuinely returns\n     nothing, so an empty directory is distinguishable from a wrong path.\n   - Listings over 200 entries are capped, with `omitted_items` giving the number dropped.\n\n2. **Get Modal Logs** (`get_modal_logs`) — fetch or stream logs for an app *or* a container.\n   - Parameters: `identifier` (required), `target` (`auto`/`app`/`container`, default\n     `auto` — anything starting `ta-` is a container), `timeout_seconds` (default 30),\n     `env`, `since`, `until`, `tail`, `source` (`stdout`/`stderr`/`system`), `timestamps`,\n     `follow`\n   - With `follow=True`, logs stream until the app/container stops or `timeout_seconds` is\n     reached, returning a snapshot with `truncated: true`.\n   - Only covers the stdout/stderr/system streams; some failures (e.g. a crash reported as\n     \"... exited with ...\") are Modal dashboard events, not log lines, and won't appear here.\n\n3. **Search Modal Logs** (`search_modal_logs`) — grep logs and get each hit **with the\n   surrounding lines**, built for \"where did it go wrong?\" debugging. Logs are fetched once\n   and searched locally, so you get context, regex, case control, and exact match counts.\n   - Parameters: `identifier` (required), `pattern` (required), `target` (default `auto`),\n     `regex`, `case_sensitive`, `context_lines` (default 3), `max_matches` (default 50),\n     `since`, `tail` (defaults to the last 1000 entries), `source`,\n     `exclude` (drop noise lines before searching, e.g. `\"queue put failed\"`),\n     `timestamps` (default `true`), `timeout_seconds`, `env`\n   - Returns `match_count` and `matches`: timestamped, line-numbered context blocks where\n     matched lines are prefixed with `>`, e.g. `> 8: 2026-06-04T... ValueError: bad input`.\n     The whole fetched log is always searched, so `match_count` stays exact even when fewer\n     blocks are returned. Reports `excluded_lines` when `exclude` is used.\n   - Same stdout/stderr/system-only caveat as `get_modal_logs`.\n\n### Deploy & run\n\n4. **Deploy Modal App** (`deploy_modal_app`)\n   - Deploys a Modal app (`modal deploy`). Deployed web endpoints persist, so any links in\n     the output are live and shareable (returned in `urls`).\n   - Parameters: `absolute_path_to_app` (required), `env`, `name`, `tag`,\n     `strategy` (`rolling`/`recreate`), `stream_logs`\n   - The app's directory must use `uv` with `modal` installed in its virtualenv.\n\n5. **Run Modal App** (`run_modal_app`)\n   - Runs a function or local entrypoint once and collects its output (`modal run`).\n   - Parameters: `absolute_path_to_app` (required), `function_name`, `env`, `detach`,\n     `timeout_seconds` (default 120)\n   - Returns a snapshot with `truncated: true` if the run is still going at the timeout.\n     Pass `detach=True` to keep long jobs alive on Modal past the timeout.\n\n> **Why no `modal serve` tool?** `modal serve` only keeps its endpoints alive while the\n> blocking process runs — an MCP tool that returns would tear them down immediately,\n> handing back a dead URL. Use `deploy_modal_app` for a persistent, shareable endpoint.\n\n### State changes\n\n6. **Manage Modal App** (`manage_modal_app`) — `action` is `stop` (shut the app down and\n   terminate its containers) or `rollback` (redeploy a previous version).\n   - Parameters: `action` (required), `app_identifier` (required), `version` (rollback\n     only — defaults to the immediately preceding version), `env`\n\n7. **Manage Modal Container** (`manage_modal_container`) — `action` is `exec` (run a command\n   inside a running container, `modal container exec --no-pty`) or `stop` (terminate it).\n   - Parameters: `action` (required), `container_id` (required), `command` (exec only —\n     a list of args, e.g. `[\"python\", \"-c\", \"print('hi')\"]`), `timeout_seconds` (default 60)\n\n8. **Manage Modal Volume** (`manage_modal_volume`) — `action` is `create`, `delete`\n   (the volume **and all its data**, irreversible), or `rename`.\n   - Parameters: `action` (required), `volume_name` (required), `new_name` (rename only), `env`\n\n9. **Modal Volume Files** (`modal_volume_files`) — write operations on a volume's files:\n   `action` is `put` (upload), `get` (download), `cp` (copy inside the volume), or `rm`.\n   - Parameters: `action` (required), `volume_name` (required), `local_path`, `remote_path`,\n     `paths` (for `cp`: sources then destination), `recursive`, `force`, `env`\n   - `action=\"get\"` with `local_path=\"-\"` returns the file contents instead of writing a file.\n   - To *list* a volume's contents use `list_modal_resources(resource=\"volume_files\")`.\n\n10. **Manage Modal Secret** (`manage_modal_secret`) — `action` is `create` or `delete`.\n    - Parameters: `action` (required), `secret_name` (required), `key_values` (dict),\n      `from_dotenv` (path), `from_json` (path), `force`, `env`. Creating requires at least\n      one of `key_values`, `from_dotenv`, or `from_json`.\n    - Secret values are redacted from every field returned, including error output.\n    - To list secret names use `list_modal_resources(resource=\"secrets\")`.\n\n### Costs\n\n11. **Analyze Modal Costs** (`analyze_modal_costs`) — read-only. Fetches\n    `modal billing` once and aggregates locally, so you get ranked totals and\n    period-over-period changes instead of hundreds of raw rows.\n    - Parameters: `view` (default `by_app`), `period`, `start`, `end`, `resolution`\n      (`d`/`h`), `timezone`, `app`, `environment`, `top_n` (default 10), `tag_names`\n    - `view` values:\n      | value | answers |\n      | --- | --- |\n      | `by_app` | \"what is my costliest app?\" — apps ranked by spend, with % share |\n      | `timeline` | \"why was Monday expensive?\" — cost per interval, plus an `explanation` that diffs the peak interval against the one before and ranks which apps grew |\n      | `by_environment` | which environment the money goes to |\n      | `by_resource` | CPU vs GPU class vs memory vs storage |\n      | `summary` | billed vs metered cost for a month cycle, with credits/plan adjustments |\n      | `rates` | current unit prices |\n    - `total_cost` always covers every row in range, even when `groups` is cut to\n      `top_n` — quote it rather than summing the visible rows.\n    - Billing is workspace-wide (the CLI takes no `-e`), so this reports across all\n      environments; `environment` filters the rows afterwards.\n    - Modal reports **whole intervals only**, so a partially elapsed day reads low.\n\n### Secrets — inspection\n\n12. **Inspect Modal Secret** (`inspect_modal_secret`) — lists the **key names** inside a\n    secret, never the values.\n    - Parameters: `secret_name` (required), `env`, `image`, `timeout_seconds` (default 300)\n    - Modal exposes no API for this by design: not the CLI, not the SDK, not the gRPC\n      layer. The only way to see which keys a secret defines is to mount it in a container\n      and list the environment. So this tool runs `modal shell --secret <name>` with\n      `compgen -e` (a bash builtin that prints exported variable *names* only — no value is\n      ever printed, even inside the container), then subtracts the ~35 variables the image\n      and Modal runtime set anyway.\n    - **This one call starts remote compute**, so it costs a few cents and takes tens of\n      seconds (longer when the image has to build). Every other read in this server is\n      free; use `list_modal_resources(resource=\"secrets\")` to see *which* secrets exist and\n      reach for this only when you need to know what is *inside* one.\n    - Returns `keys`, plus the unfiltered `all_env_names` so a key that looks like a\n      runtime variable is still visible rather than silently dropped.\n    - Omit `image` to use Modal's default (built to match the server's Python — the most\n      reliable choice). Pass one, e.g. `python:3.12-slim`, if your workspace's image\n      builder rejects that Python version.\n\n## Prompts\n\nThe server also ships four MCP prompts — multi-step workflows your client can invoke\ndirectly (in Claude Code they appear as `/mcp__mcp-modal__<name>`). Prompts are fetched on\ndemand, so unlike tools they cost nothing in per-session context:\n\n- **`debug_modal_app`** (`app_name`, optional `symptom`) — an ordered triage routine: check\n  the app is up, search logs for tracebacks with context, fall back to the log tail,\n  inspect containers, then compare against deployment history and consider a rollback.\n- **`deploy_and_verify`** (`absolute_path_to_app`, optional `env`) — confirm the target\n  workspace, deploy, report the live URLs, then *verify* the app is healthy instead of\n  assuming it.\n- **`review_modal_account`** (optional `env`) — a read-only inventory that flags idle apps,\n  unexplained running containers, and orphaned volumes/secrets, naming the exact call that\n  would clean each one up without running it.\n- **`investigate_modal_costs`** (optional `period`, `app`) — traces a spend increase from\n  the daily timeline down to the peak hour, the resource class, and the deploy or\n  still-running container behind it.\n\n## Output caps\n\nLog, run, and exec output is capped before it is returned, so one chatty app can't flood\nyour context window. The default budget is 40,000 characters per text field (roughly 10k\ntokens); when a field is trimmed the result sets `output_capped: true` and the text carries\na marker naming how much was dropped. A capped field keeps its head *and* its tail, so a\nstartup banner and the traceback at the end both survive.\n\nSearching is never capped before the fact: `search_modal_logs` greps the whole fetched log\nand only limits how many context blocks come back, so `match_count` is always exact.\n\nSet `MCP_MODAL_MAX_OUTPUT_CHARS` to raise or lower the budget, or to `0` to disable capping\nentirely:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-modal\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-modal\"],\n      \"env\": { \"MCP_MODAL_MAX_OUTPUT_CHARS\": \"80000\" }\n    }\n  }\n}\n```\n\n## Upgrading from 0.2.x\n\n0.3.0 replaces the 26 single-purpose tools with 10 grouped ones. Nothing was dropped — every\noperation is still reachable — but the names and arguments changed:\n\n| 0.2.x | 0.3.0 |\n| --- | --- |\n| `list_modal_apps` | `list_modal_resources(resource=\"apps\")` |\n| `get_modal_app_history` | `list_modal_resources(resource=\"app_history\", name=...)` |\n| `list_modal_containers` | `list_modal_resources(resource=\"containers\")` |\n| `list_modal_volumes` | `list_modal_resources(resource=\"volumes\")` |\n| `list_modal_volume_contents` | `list_modal_resources(resource=\"volume_files\", name=...)` |\n| `list_modal_secrets` | `list_modal_resources(resource=\"secrets\")` |\n| `list_modal_environments` | `list_modal_resources(resource=\"environments\")` |\n| `get_modal_profile` | `list_modal_resources(resource=\"profile\")` |\n| `get_modal_app_logs` / `get_modal_container_logs` | `get_modal_logs` (auto-detects the target) |\n| `stop_modal_app` / `rollback_modal_app` | `manage_modal_app(action=\"stop\"/\"rollback\")` |\n| `exec_modal_container` / `stop_modal_container` | `manage_modal_container(action=\"exec\"/\"stop\")` |\n| `create_modal_volume` / `delete_modal_volume` / `rename_modal_volume` | `manage_modal_volume(action=...)` |\n| `put_modal_volume_file` / `get_modal_volume_file` / `copy_modal_volume_files` / `remove_modal_volume_file` | `modal_volume_files(action=\"put\"/\"get\"/\"cp\"/\"rm\")` |\n| `create_modal_secret` / `delete_modal_secret` | `manage_modal_secret(action=\"create\"/\"delete\")` |\n\nAlso new in 0.3.0: every volume tool now accepts `env` (volumes are environment-scoped, and\n0.2.x silently used the default environment for file operations), `modal_volume_files`\nsupports `recursive` for `cp`, and `search_modal_logs`/`get_modal_logs` accept\n`target=\"auto\"`. The redundant `search` argument on the log tools is gone — use\n`search_modal_logs`, which returns context instead of bare matching lines.\n\n## Response Format\n\nAll tools return responses in a standardized format, with slight variations depending on the operation type:\n\n```python\n# Lookups (list_modal_resources):\n{\n    \"success\": True,\n    \"apps\": [...],          # or \"containers\", \"volumes\", \"contents\", \"secrets\", ...\n    \"omitted_items\": 0      # present when the listing was capped at 200 entries\n}\n\n# Action operations (deploy, stop, rollback, create, delete, rename, cp, put, get, rm):\n{\n    \"success\": True,\n    \"message\": \"Operation successful message\",\n    \"command\": \"executed command string\",\n    \"stdout\": \"command output\",  # if any\n    \"stderr\": \"error output\"     # if any\n}\n\n# Log / run / exec operations (snapshot-based):\n{\n    \"success\": True,\n    \"logs\": \"...\",          # or \"output\" for run/exec\n    \"truncated\": False,     # True when cut off at timeout_seconds\n    \"output_capped\": False, # True when text was trimmed to fit MCP_MODAL_MAX_OUTPUT_CHARS\n    \"command\": \"executed command string\"\n}\n\n# Error case (all operations):\n{\n    \"success\": False,\n    \"error\": \"Error message describing what went wrong\",\n    \"command\": \"executed command string\",\n    \"stdout\": \"command output\",  # if available\n    \"stderr\": \"error output\"     # if available\n}\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
  "bytes": 20980,
  "sha": "c41fd7d99c48283a52a02809de15176043cf2063752f067a4cce9ba910e37503",
  "repo_slug": "george-bobby/mcp-modal",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_george_bobby_mcp_modal_2d57c383/readme"
}