mcp-modal

<!-- mcp-name: io.github.george-bobby/mcp-modal -->

# MCP Modal Server

[![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)

[![PyPI](https://img.shields.io/pypi/v/mcp-modal.svg)](https://pypi.org/project/mcp-modal/)

An 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.


Every 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.

## Installation

The 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)).

Every version is also tagged and published on the
[Releases page](https://github.com/george-bobby/mcp-modal/releases), with release notes and
the same `.whl` / `.tar.gz` that PyPI serves attached — useful for pinning, air-gapped
installs, or reading what changed between two versions.

## Logging in to Modal

This server uses your local Modal credentials. If you haven't authenticated yet, run:

```bash
modal setup
```

This opens a browser to log in and stores a token in `~/.modal.toml`. Already logged in elsewhere? Check with `modal profile current`.

## Configuration

Add the server to Claude Code with the `claude mcp` CLI:

```bash
claude mcp add mcp-modal -- uvx mcp-modal@latest
```

Or add it to a `.mcp.json` file in your project root, which is the better option for a team
— everyone who opens the repo gets the same configuration:

```json
{
  "mcpServers": {
    "mcp-modal": {
      "command": "uvx",
      "args": ["mcp-modal@latest"]
    }
  }
}
```

### Why `@latest`, and when to pin instead

`uvx` caches the environment it builds on the first run and **does not check PyPI again**:

> "uvx will use the latest available version of the requested tool on the first invocation.
> After that, uvx will use the cached version of the tool unless a different version is
> requested, the cache is pruned, or the cache is refreshed."
> — [uv docs](https://docs.astral.sh/uv/concepts/tools/)

So a plain `uvx mcp-modal` means *latest at install time, frozen forever after* — restarting
the client or rebooting changes nothing, because the cache lives on disk. Different people
end up on different versions depending on when they first ran it, with no warning.

- **`mcp-modal@latest`** re-resolves on every launch, so a restart picks up new releases.
  Costs one network round-trip at startup. Use it while the tool surface is still moving.
- **`mcp-modal@0.4.0`** (an explicit version) is reproducible and upgrades become a
  deliberate one-line change. Use it once you want stability, or for a wider audience.

To move a machine that is already stuck on an old cached build, switching it to either form
above is enough — requesting a version invalidates the cache. Otherwise
`uv cache clean mcp-modal` forces a refresh.

## Requirements

- Python 3.11 or higher
- [`uv`](https://docs.astral.sh/uv/) (provides `uvx`)
- Modal CLI 1.5 or newer, configured with valid credentials (`modal setup`) — 1.5 is
  where `modal billing summary`/`rates` landed and where the billing report switched to
  snake_case columns; the cost tool reads both spellings but needs 1.5 for those two views
- For Modal **deploy** and **run** support:
  - The project being deployed/run must use `uv` for dependency management
  - `modal` must be installed in that project's virtual environment

## Security

This server shells out to your local `modal` CLI using whatever credentials are in
`~/.modal.toml`. A few tools are powerful by design — if the MCP client driving the server
is ever prompt-injected (for example by malicious text inside logs it fetched), these are
the escalation paths and should stay **behind your client's tool-approval prompts** rather
than being auto-approved:

- **`deploy_modal_app` / `run_modal_app`** — execute arbitrary local Python on the host
  (`modal deploy` imports the app file; `uv run` resolves and installs the target project's
  dependencies).
- **`modal_volume_files`** with `action="put"` — can read any local file (e.g. `~/.ssh/id_rsa`,
  `~/.modal.toml`) and upload it to a cloud volume (a data-exfiltration primitive).
- **`modal_volume_files`** with `action="get"` and `force=True` — can overwrite any local path
  (e.g. `~/.zshrc` or a shell profile, a persistence primitive).
- **`manage_modal_container`** with `action="exec"` — runs arbitrary commands inside a
  container, by design.

Every tool declares [MCP tool annotations](https://modelcontextprotocol.io/specification/server/tools#tool-annotations),
so a client can distinguish the four read-only tools (`list_modal_resources`,
`get_modal_logs`, `search_modal_logs`, `analyze_modal_costs` — all `readOnlyHint: true`)
from the eight that change remote state or start compute. Six of those eight are
`destructiveHint: true`; the exceptions are `run_modal_app` and `inspect_modal_secret`,
which start compute without removing or overwriting anything. Auto-approve the reads; keep
the rest behind a prompt.

### Optional local-path allowlist

To contain the two filesystem-touching volume tools, set the
`MCP_MODAL_ALLOWED_LOCAL_PATHS` environment variable to an
[`os.pathsep`](https://docs.python.org/3/library/os.html#os.pathsep)-separated list of
directories (`:` on macOS/Linux). When it is set, `modal_volume_files` is refused for any
local path — `local_path` on `action="put"`, the destination on `action="get"` — unless the
resolved path, after expanding `~` and collapsing `..`/symlinks, falls inside one of those
roots. The download target `"-"` (return contents instead of writing a file) is exempt
because nothing is written to disk.

When the variable is **unset (the default) there is no restriction**, so existing setups are
unaffected. Configure it in your MCP client, e.g.:

```json
{
  "mcpServers": {
    "mcp-modal": {
      "command": "uvx",
      "args": ["mcp-modal"],
      "env": { "MCP_MODAL_ALLOWED_LOCAL_PATHS": "/Users/me/modal-workspace:/tmp/modal" }
    }
  }
}
```

All tools also pass user-supplied names/paths after a `--` end-of-options separator, so a
value beginning with `-` is always treated as data, never as a `modal` CLI flag. Secret
values handed to `manage_modal_secret` are redacted from the echoed command, logs, and any
error output.

## Supported Tools

12 tools. Related operations are grouped behind an `action`/`resource` argument rather than
split one-per-CLI-subcommand: every tool schema is loaded into the model's context for the
whole session, so a smaller surface leaves more room for your actual work (and gives the
model fewer near-identical tools to choose between).

Tools that talk to environment-scoped resources take an optional `env` argument to target a
specific [Modal environment](https://modal.com/docs/guide/environments); if omitted, they
use the profile's default (or `MODAL_ENVIRONMENT`). The exception is `manage_modal_container`
and container logs — a container ID is globally unique and the CLI accepts no environment
there.

### Read-only

1. **List Modal Resources** (`list_modal_resources`) — one lookup for the whole account.
   - Parameters: `resource` (required), `name`, `path` (default `/`), `env`
   - `resource` values:
     | value | returns | `name` means |
     | --- | --- | --- |
     | `apps` | deployed/running/recently-stopped apps | — |
     | `app_history` | one app's deployment versions (for rollback) | app name/ID |
     | `containers` | running containers (`ta-...`) | app ID to filter by |
     | `volumes` | named volumes | — |
     | `volume_files` | files inside a volume (with `path`) | volume name |
     | `secrets` | secret names (values are never exposed) | — |
     | `environments` | valid `env` values for this workspace | — |
     | `profile` | active profile + all profiles | — |
   - `volume_files` sets `empty: true` with a message when a listing genuinely returns
     nothing, so an empty directory is distinguishable from a wrong path.
   - Listings over 200 entries are capped, with `omitted_items` giving the number dropped.

2. **Get Modal Logs** (`get_modal_logs`) — fetch or stream logs for an app *or* a container.
   - Parameters: `identifier` (required), `target` (`auto`/`app`/`container`, default
     `auto` — anything starting `ta-` is a container), `timeout_seconds` (default 30),
     `env`, `since`, `until`, `tail`, `source` (`stdout`/`stderr`/`system`), `timestamps`,
     `follow`
   - `since` without `tail` fetches *every* entry in the range; pass `until` as well (max
     range 35 days, `tail` max 20,000) to keep a busy app's output bounded.
   - With `follow=True`, logs stream until the app/container stops or `timeout_seconds` is
     reached, returning a snapshot with `truncated: true`.
   - Only covers the stdout/stderr/system streams; some failures (e.g. a crash reported as
     "... exited with ...") are Modal dashboard events, not log lines, and won't appear here.

3. **Search Modal Logs** (`search_modal_logs`) — grep logs and get each hit **with the
   surrounding lines**, built for "where did it go wrong?" debugging. Logs are fetched once
   and searched locally, so you get context, regex, case control, and exact match counts.
   - Parameters: `identifier` (required), `pattern` (required), `target` (default `auto`),
     `regex`, `case_sensitive`, `context_lines` (default 3), `max_matches` (default 50),
     `since`, `until`, `tail` (defaults to the last 1000 entries), `source`,
     `exclude` (drop noise lines before searching, e.g. `"queue put failed"`),
     `prefi