Modal MCP
Manage Modal from an MCP client using your existing Modal CLI login: inspect resources, logs, costs, deploy/run apps, and administer containers, volumes, and secrets.
List apps, app history, containers, volumes, volume files, secrets, environments, and profiles.
Fetch/follow logs and search logs with context, regex, filters, and time ranges.
Analyze billing by app, environment, resource, timeline, summary, or rates; explain cost spikes.
Deploy Modal apps and run functions/entrypoints, returning live URLs and output.
Stop or roll back apps, and exec commands in or stop containers.
Create, delete, or rename volumes; upload, download, copy, or remove volume files.
Create or delete secrets; inspect secret key names without exposing values.
Supports read-only/destructive hints, output caps, and allowed local path configuration.
Provides tools for managing Modal apps, containers, volumes, and secrets, enabling deployment and execution of Modal apps directly from MCP clients.
MCP Modal Server
An MCP server for managing Modal — apps, containers, volumes, and secrets — and for deploying & running Modal apps directly from 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. No manual install is needed — the recommended way to run it is with uvx, which fetches and launches it on demand. Just point your MCP client at the command below (see Configuration).
Every version is also tagged and published on the
Releases page, 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.
Related MCP server: MCP Server Modal
Logging in to Modal
This server uses your local Modal credentials. If you haven't authenticated yet, run:
modal setupThis 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:
claude mcp add mcp-modal -- uvx mcp-modal@latestOr 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:
{
"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
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@latestre-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(providesuvx)Modal CLI 1.5 or newer, configured with valid credentials (
modal setup) — 1.5 is wheremodal billing summary/rateslanded and where the billing report switched to snake_case columns; the cost tool reads both spellings but needs 1.5 for those two viewsFor Modal deploy and run support:
The project being deployed/run must use
uvfor dependency managementmodalmust 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 deployimports the app file;uv runresolves and installs the target project's dependencies).modal_volume_fileswithaction="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_fileswithaction="get"andforce=True— can overwrite any local path (e.g.~/.zshrcor a shell profile, a persistence primitive).manage_modal_containerwithaction="exec"— runs arbitrary commands inside a container, by design.
Every tool declares MCP 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-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.:
{
"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; 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
List Modal Resources (
list_modal_resources) — one lookup for the whole account.Parameters:
resource(required),name,path(default/),envresourcevalues:value
returns
namemeansappsdeployed/running/recently-stopped apps
—
app_historyone app's deployment versions (for rollback)
app name/ID
containersrunning containers (
ta-...)app ID to filter by
volumesnamed volumes
—
volume_filesfiles inside a volume (with
path)volume name
secretssecret names (values are never exposed)
—
environmentsvalid
envvalues for this workspace—
profileactive profile + all profiles
—
volume_filessetsempty: truewith 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_itemsgiving the number dropped.
Get Modal Logs (
get_modal_logs) — fetch or stream logs for an app or a container.Parameters:
identifier(required),target(auto/app/container, defaultauto— anything startingta-is a container),timeout_seconds(default 30),env,since,until,tail,source(stdout/stderr/system),timestamps,followsincewithouttailfetches every entry in the range; passuntilas well (max range 35 days,tailmax 20,000) to keep a busy app's output bounded.With
follow=True, logs stream until the app/container stops ortimeout_secondsis reached, returning a snapshot withtruncated: 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.
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(defaultauto),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"),prefilter,timestamps(defaulttrue),timeout_seconds,envBound the window on a busy app.
sinceon its own fetches everything from then until now — hundreds of KB per hour on a chatty app, which the 30s fetch cuts off (logs_truncated: true) and the output budget trims.sinceanduntilaround the minute you care about is the fix, and is usually kilobytes.prefilter=Truepushespatterndown to Modal as a server-side substring filter (modal app logs --search), so non-matching lines are never fetched — the lever for logs too large to drain. Requiresregex=False, and context lines then show only other matches, so use it to locate the window and re-query it withprefilter=False.Returns
match_countandmatches: timestamped, line-numbered context blocks where matched lines are prefixed with>, e.g.> 8: 2026-06-04T... ValueError: bad input. The whole fetched log is always searched, somatch_countstays exact even when fewer blocks are returned.returnedis how many matches came back (adjacent matches merge into one block, counted byreturned_blocks). Reportsexcluded_lineswhenexcludeis used.A window the CLI rejects (reversed range, over 35 days,
tailover 20,000) comes back assuccess: falsewith Modal's own message, not a bare exit code.Same stdout/stderr/system-only caveat as
get_modal_logs.
Deploy & run
Deploy Modal App (
deploy_modal_app)Deploys a Modal app (
modal deploy). Deployed web endpoints persist, so any links in the output are live and shareable (returned inurls).Parameters:
absolute_path_to_app(required),env,name,tag,strategy(rolling/recreate),stream_logsThe app's directory must use
uvwithmodalinstalled in its virtualenv.
Run Modal App (
run_modal_app)Runs a function or local entrypoint once and collects its output (
modal run).Parameters:
absolute_path_to_app(required),function_name,env,detach,timeout_seconds(default 120)Returns a snapshot with
truncated: trueif the run is still going at the timeout. Passdetach=Trueto keep long jobs alive on Modal past the timeout.
Why no
modal servetool?modal serveonly keeps its endpoints alive while the blocking process runs — an MCP tool that returns would tear them down immediately, handing back a dead URL. Usedeploy_modal_appfor a persistent, shareable endpoint.
State changes
Manage Modal App (
manage_modal_app) —actionisstop(shut the app down and terminate its containers) orrollback(redeploy a previous version).Parameters:
action(required),app_identifier(required),version(rollback only — defaults to the immediately preceding version),env
Manage Modal Container (
manage_modal_container) —actionisexec(run a command inside a running container,modal container exec --no-pty) orstop(terminate it).Parameters:
action(required),container_id(required),command(exec only — a list of args, e.g.["python", "-c", "print('hi')"]),timeout_seconds(default 60)
Manage Modal Volume (
manage_modal_volume) —actioniscreate,delete(the volume and all its data, irreversible), orrename.Parameters:
action(required),volume_name(required),new_name(rename only),env
Modal Volume Files (
modal_volume_files) — write operations on a volume's files:actionisput(upload),get(download),cp(copy inside the volume), orrm.Parameters:
action(required),volume_name(required),local_path,remote_path,paths(forcp: sources then destination),recursive,force,envaction="get"withlocal_path="-"returns the file contents instead of writing a file.To list a volume's contents use
list_modal_resources(resource="volume_files").
Manage Modal Secret (
manage_modal_secret) —actioniscreateordelete.Parameters:
action(required),secret_name(required),key_values(dict),from_dotenv(path),from_json(path),force,env. Creating requires at least one ofkey_values,from_dotenv, orfrom_json.Secret values are redacted from every field returned, including error output.
To list secret names use
list_modal_resources(resource="secrets").
Costs
Analyze Modal Costs (
analyze_modal_costs) — read-only. Fetchesmodal billingonce and aggregates locally, so you get ranked totals and period-over-period changes instead of hundreds of raw rows.Parameters:
view(defaultby_app),period,start,end,resolution(d/h),timezone,app,environment,top_n(default 10),tag_namesviewvalues:value
answers
by_app"what is my costliest app?" — apps ranked by spend, with % share
timeline"why was Monday expensive?" — cost per interval, plus an
explanationthat diffs the peak interval against the one before and ranks which apps grewby_environmentwhich environment the money goes to
by_resourceCPU vs GPU class vs memory vs storage
summarybilled vs metered cost for a month cycle, with credits/plan adjustments
ratescurrent unit prices
total_costalways covers every row in range, even whengroupsis cut totop_n— quote it rather than summing the visible rows.Billing is workspace-wide (the CLI takes no
-e), so this reports across all environments;environmentfilters the rows afterwards.Modal reports whole intervals only, so a partially elapsed day reads low.
Secrets — inspection
Inspect Modal Secret (
inspect_modal_secret) — lists the key names inside a secret, never the values.Parameters:
secret_name(required),env,image,timeout_seconds(default 300)Modal exposes no API for this by design: not the CLI, not the SDK, not the gRPC layer. The only way to see which keys a secret defines is to mount it in a container and list the environment. So this tool runs
modal shell --secret <name>withcompgen -e(a bash builtin that prints exported variable names only — no value is ever printed, even inside the container), then subtracts the variables the image and Modal runtime set anyway — 23 known names plus anything under six prefixes (MODAL_,PYTHON,PIP_,NVIDIA_,CUDA_,LD_LIBRARY_PATH), which also covers theMODAL_TOKEN_*credentials that live in every container.This one call starts remote compute, so it costs a few cents and takes tens of seconds (longer when the image has to build). Every other read in this server is free; use
list_modal_resources(resource="secrets")to see which secrets exist and reach for this only when you need to know what is inside one.Returns
keys, plus the unfilteredall_env_namesso a key that looks like a runtime variable is still visible rather than silently dropped.Omit
imageto use Modal's default (built to match the server's Python — the most reliable choice). Pass one, e.g.python:3.12-slim, if your workspace's image builder rejects that Python version.
Prompts
The server also ships four MCP prompts — multi-step workflows your client can invoke
directly (in Claude Code they appear as /mcp__mcp-modal__<name>). Prompts are fetched on
demand, so unlike tools they cost nothing in per-session context:
debug_modal_app(app_name, optionalsymptom) — an ordered triage routine: check the app is up, search logs for tracebacks with context, narrow the window instead of widening it when a log fetch comes back truncated, fall back to the log tail, check whether sibling apps were hit in the same window, inspect containers, then compare against deployment history and consider a rollback.deploy_and_verify(absolute_path_to_app, optionalenv) — confirm the target workspace, deploy, report the live URLs, then verify the app is healthy instead of assuming it.review_modal_account(optionalenv) — a read-only inventory that flags idle apps, unexplained running containers, and orphaned volumes/secrets, naming the exact call that would clean each one up without running it.investigate_modal_costs(optionalperiod,app) — traces a spend increase from the daily timeline down to the peak hour, the resource class, and the deploy or still-running container behind it.
Output caps
Log, run, and exec output is capped before it is returned, so one chatty app can't flood
your context window. The default budget is 40,000 characters per text field (roughly 10k
tokens); when a field is trimmed the result sets output_capped: true and the text carries
a marker naming how much was dropped. A capped field keeps its head and its tail, so a
startup banner and the traceback at the end both survive.
Searching is never capped before the fact: search_modal_logs greps the whole fetched log
and only limits how many context blocks come back, so match_count is always exact.
Raising timeout_seconds or the budget is rarely the right answer to a truncated log
search — fetching less is. Bound the window with since and until, filter with
source/exclude, or set prefilter=True to drop non-matching lines inside Modal.
Set MCP_MODAL_MAX_OUTPUT_CHARS to raise or lower the budget, or to 0 to disable capping
entirely:
{
"mcpServers": {
"mcp-modal": {
"command": "uvx",
"args": ["mcp-modal"],
"env": { "MCP_MODAL_MAX_OUTPUT_CHARS": "80000" }
}
}
}Response Format
All tools return responses in a standardized format, with slight variations depending on the operation type:
# Lookups (list_modal_resources):
{
"success": True,
"apps": [...], # or "containers", "volumes", "contents", "secrets", ...
"omitted_items": 0 # present when the listing was capped at 200 entries
}
# Action operations (deploy, stop, rollback, create, delete, rename, cp, put, get, rm):
{
"success": True,
"message": "Operation successful message",
"command": "executed command string",
"stdout": "command output", # if any
"stderr": "error output" # if any
}
# Log / run / exec operations (snapshot-based):
{
"success": True,
"logs": "...", # or "output" for run/exec
"truncated": False, # True when cut off at timeout_seconds
"output_capped": False, # True when text was trimmed to fit MCP_MODAL_MAX_OUTPUT_CHARS
"command": "executed command string"
}
# Log search (search_modal_logs):
{
"success": True,
"match_count": 12, # exact: the whole fetched log is searched
"returned": 5, # matches actually shown
"returned_blocks": 2, # adjacent matches merge into one context block
"matches": ["> 8: ...", ...],
"logs_truncated": False, # True when the log fetch hit timeout_seconds
"output_capped": False,
"command": "executed command string"
}
# Error case (all operations):
{
"success": False,
"error": "Error message describing what went wrong",
"command": "executed command string",
"stdout": "command output", # if available
"stderr": "error output" # if available
}License
This project is licensed under the MIT License - see the LICENSE file for details.
Available Tools
12 toolsanalyze_modal_costsARead-onlyIdempotent
Break down what the workspace is spending (`modal billing`). Costs are fetched once
and aggregated locally, so you get ranked totals and period-over-period changes
rather than hundreds of raw rows.
Answering common questions:
"what is my costliest app?" -> view="by_app", period="this month"
"why was Monday expensive?" -> view="timeline", period="last week" (the
`explanation` field diffs the peak day against
the day before and ranks which apps grew)
"what did that day cost hourly?" -> view="timeline", start="2026-08-31",
end="2026-09-01", resolution="h"
"where does the money go?" -> view="by_resource" (CPU / GPU / memory / ...)
"what is the bill this cycle?" -> view="summary"
Billing is workspace-wide, so this reports across every environment; use
`environment` to narrow it after the fact.
Args:
view: "by_app" (default), "timeline" (per interval, with an explanation of the
peak), "by_environment", "by_resource", "summary" (billed vs metered for a
month cycle), or "rates" (current unit prices).
period: Convenience range — "today", "yesterday", "this week", "last week",
"this month", "last month". For "summary" also accepts "YYYY-MM".
start / end: Explicit range instead of `period` — ISO dates ("2026-08-31") or
relative ("3 days ago"). Start is inclusive, end exclusive; end defaults to now.
resolution: "d" (daily, default) or "h" (hourly). Hourly is what you want when
drilling into a single day.
timezone: Timezone for interpreting dates — "local", an offset ("+05:30"), or an
IANA name. Requires resolution="h".
app: Only include apps whose name or ID contains this string (case-insensitive).
environment: Only include rows from this Modal environment.
top_n: How many groups/movers to return. Default 10.
tag_names: Comma-separated cost-attribution tag names to include.
profile: Modal profile for this call only. Defaults to the active profile.
Returns: {total_cost, groups | intervals, explanation (for timeline), row_count}.
Costs are strings of US dollars with 4 decimals. `total_cost` always covers every
row in range, even when `groups` is cut to top_n.
Inputs: app, end, view, start, +7 more. Returns: result
deploy_modal_appADestructive
Deploy a Modal app (`modal deploy`). Deployed endpoints persist after this returns,
so any URLs in the result are live, shareable links.
Args:
absolute_path_to_app: Absolute path to the app file. Its directory must use `uv`
and have `modal` installed in its virtualenv.
env: Modal environment to deploy into.
name: Deployment name (`--name`).
tag: Version tag (`--tag`).
strategy: Rollout strategy — "rolling" or "recreate".
stream_logs: Stream the app's logs after deploying.
profile: Modal profile for this call only. Defaults to the active profile.
Returns: {message, urls (live endpoints), stdout, stderr}.
Inputs: absolute_path_to_app (required), env, tag, name, +3 more. Returns: result
get_modal_logsARead-onlyIdempotent
Fetch logs for an app or container (`modal app logs` / `modal container logs`).
To find where something went wrong, prefer search_modal_logs — it returns matches
with surrounding context instead of a raw tail.
Covers the stdout/stderr/system streams ONLY. Crash events shown on the Modal
dashboard (e.g. "... exited with ...") are not log lines and never appear here.
Args:
identifier: App name/ID ("my-app", "ap-...") or container ID ("ta-...").
target: "auto" (default — "ta-..." is a container), "app", or "container".
timeout_seconds: Max seconds to collect. Default 30.
env: Modal environment. Apps only — container logs take no environment.
since / until: Time range, ISO 8601 or relative ("2h", "30m", "1d"). Max 35 days.
`since` without `tail` fetches EVERY entry in the range — pass `until` too
(or a `tail`) to bound the volume on a busy app.
tail: Only the last N entries (max 20000).
source: "stdout", "stderr", or "system".
timestamps: Prefix each line with its wall-clock timestamp.
follow: Live-stream until the app/container stops or the timeout hits.
profile: Modal profile for this call only. Defaults to the active profile.
Returns: {logs, truncated (still streaming at the timeout), output_capped (text
trimmed to fit context — narrow with tail/since/source)}.
Inputs: identifier (required), env, tail, since, +7 more. Returns: result
inspect_modal_secretA
List the KEY NAMES inside a Modal secret — never the values.
Modal exposes no API for this: neither the CLI, the SDK, nor the gRPC layer can read
a secret's contents, by design. The only way to see which keys a secret defines is to
mount it in a container and look at the environment variable names. So this tool
starts a short-lived container (`modal shell --secret ...`), prints the variable NAMES
only, and subtracts the ones the image and the Modal runtime would have set anyway.
That means, unlike every other read in this server, a call here **starts remote
compute and costs a few cents** (and takes tens of seconds — longer on the first run
for a given image, which has to be built). It is not a free lookup: use
list_modal_resources(resource="secrets") to see which secrets exist, and reach for
this only when you need to know what is inside one.
Values never leave the container: the probe is `compgen -e`, a bash builtin that
prints exported variable NAMES only, so no value is ever printed or read.
Args:
secret_name: Name of the secret, from list_modal_resources(resource="secrets").
env: Modal environment the secret lives in.
image: Optional container image. Omit it to use Modal's default image, which is
built to match this server's Python — that is the most reliable choice. Pass one
(e.g. "python:3.12-slim") if the workspace's image builder rejects that Python.
timeout_seconds: Max seconds to wait, including image build. Default 300.
profile: Modal profile for this call only. Defaults to the active profile.
Returns: {keys: [...names...], all_env_names: [...], filtered_out: n}. `all_env_names`
is the unfiltered list, so a key that looks like a runtime variable (e.g. one
literally named "PATH") is still visible rather than silently dropped.
Inputs: secret_name (required), env, image, profile, +1 more. Returns: result
list_modal_resourcesARead-onlyIdempotent
Read-only lookup of everything in the Modal account. Start here to find the app name,
container ID or volume name that the other tools take.
Args:
resource: One of:
"apps" — deployed/running/recently-stopped apps.
"app_history" — one app's deployment versions (`name` = app name/ID); use it
to pick a version for manage_modal_app(action="rollback").
"containers" — running containers ("ta-..."); `name` = app ID to filter.
"volumes" — named volumes.
"volume_files" — files in a volume (`name` = volume, plus `path`).
"secrets" — secret names only; values are never returned.
"environments" — valid values for every `env` argument.
"profile" — active profile + all profiles (which account am I?).
name: App name/ID, app ID filter, or volume name — see `resource`.
path: Path inside the volume for "volume_files". Default "/".
env: Modal environment. Ignored for "environments"/"profile".
profile: Modal profile for this call only. Defaults to the active profile.
Returns: {<resource key>: [...]} — e.g. "apps", "containers", "contents". Listings
over 200 entries are capped, with `omitted_items` giving the count dropped.
Inputs: resource (required), env, name, path, +1 more. Returns: result
manage_modal_appADestructive
Change a deployed app's state. Both actions affect live traffic.
Args:
action: "stop" — shut the app down, ending web endpoints (`modal app stop`).
"rollback" — restore a previous deployment (`modal app rollback`).
app_identifier: App name ("my-app") or ID ("ap-...").
version: Rollback target; omit for the immediately preceding version. List valid
versions with list_modal_resources(resource="app_history", name=...).
env: Modal environment to target.
profile: Modal profile for this call only. Defaults to the active profile.
Returns: {message, stdout, stderr} or {error}.
Inputs: action (required), app_identifier (required), env, profile, +1 more. Returns: result
manage_modal_containerADestructive
Act on one running container. Find IDs with
list_modal_resources(resource="containers").
Args:
action: "exec" — run a command inside the container (`modal container exec`).
This is arbitrary remote code execution: treat it like SSH, not a lookup.
"stop" — terminate it (`modal container stop`); in-flight inputs are
cancelled and rescheduled elsewhere.
container_id: Container ID ("ta-..."). Unique across environments, so no `env`
argument is needed (the CLI accepts none for these subcommands).
command: For "exec": argv list, e.g. ["python", "-c", "print('hi')"] or
["ls", "-la", "/"].
timeout_seconds: For "exec": max seconds to wait. Default 60.
profile: Modal profile for this call only. Defaults to the active profile.
Returns: exec → {output, returncode, truncated, output_capped}; stop → {message}.
Inputs: action (required), container_id (required), command, profile, +1 more. Returns: result
manage_modal_secretADestructive
Create or delete a secret. To list secret names use
list_modal_resources(resource="secrets") — values are never readable.
Values are redacted from every field returned (command, stdout, stderr, error), so
they cannot leak back into the transcript on failure.
Args:
action: "create" or "delete".
secret_name: Secret name.
key_values: For "create": {"API_KEY": "abc", ...}.
from_dotenv / from_json: For "create": load key/values from a local file instead.
Subject to MCP_MODAL_ALLOWED_LOCAL_PATHS when it is set.
force: For "create": overwrite an existing secret.
env: Modal environment to target.
profile: Modal profile for this call only. Defaults to the active profile.
Returns: {message, stdout, stderr} or {error}, with values redacted.
Inputs: action (required), secret_name (required), env, force, +4 more. Returns: result
manage_modal_volumeADestructive
Volume lifecycle. For the files inside a volume use modal_volume_files (writes) or
list_modal_resources(resource="volume_files") (reads).
Args:
action: "create", "delete" (removes the volume and ALL its data — irreversible),
or "rename".
volume_name: Volume name (the current name, for "rename").
new_name: Required for "rename".
env: Modal environment. Volumes are environment-scoped, so this must match the
environment the volume lives in.
profile: Modal profile for this call only. Defaults to the active profile.
Returns: {message, stdout, stderr} or {error}.
Inputs: action (required), volume_name (required), env, profile, +1 more. Returns: result
modal_volume_filesADestructive
Write operations on a volume's files. To LIST a volume's contents use
list_modal_resources(resource="volume_files").
Args:
action: "put" (upload local_path → remote_path), "get" (download remote_path →
local_path; "-" returns the contents instead of writing a file), "cp" (copy
inside the volume, using `paths`), "rm" (delete remote_path).
volume_name: Volume name.
local_path: Local source ("put") or destination ("get", default ".").
remote_path: In-volume destination ("put", default "/", trailing "/" keeps the
filename), source ("get"), or target ("rm").
paths: For "cp": sources followed by the destination, e.g. ["a.txt", "dest/"].
recursive: Needed to "rm" or "cp" a directory.
force: Overwrite existing files ("put"/"get").
env: Modal environment the volume lives in.
profile: Modal profile for this call only. Defaults to the active profile.
Returns: {message, stdout, stderr} or {error}. When MCP_MODAL_ALLOWED_LOCAL_PATHS is
set, "put"/"get" are refused for local paths outside the allowlist.
Inputs: action (required), volume_name (required), env, force, +5 more. Returns: result
run_modal_appA
Run a Modal function or local entrypoint once and collect its output (`modal run`).
Use this to test on Modal compute; use deploy_modal_app to publish.
Args:
absolute_path_to_app: Absolute path to the app file. Its directory must use `uv`
and have `modal` installed in its virtualenv.
function_name: Function/entrypoint name, e.g. "main". Omit if the module has
exactly one.
env: Modal environment to target.
detach: Keep the run alive on Modal past this call (`--detach`) — for long jobs.
timeout_seconds: Max seconds to collect output. Default 120.
profile: Modal profile for this call only. Defaults to the active profile.
Returns: {output, urls, truncated (still running at the timeout), output_capped}.
Inputs: absolute_path_to_app (required), env, detach, profile, +2 more. Returns: result
search_modal_logsARead-onlyIdempotent
Search an app's or container's logs and return each hit WITH surrounding context —
the fastest way to find a traceback, an error or a request ID. Logs are fetched once
and grepped locally, so you get the lines around each match, not just the match.
Covers the stdout/stderr/system streams ONLY. Crash events shown on the Modal
dashboard (e.g. "... exited with ...") are not log lines, so a search for them
returns 0 matches even though the failure is real — check the dashboard instead.
Args:
identifier: App name/ID ("my-app", "ap-...") or container ID ("ta-...").
pattern: Text to find, or a Python regex when regex=True.
target: "auto" (default — "ta-..." is a container), "app", or "container".
regex / case_sensitive: Match mode. Both default False.
context_lines: Lines of context each side of a match. Default 3.
max_matches: Cap on match blocks returned. Default 50.
since / until: Time range, ISO 8601 or relative ("2h", "30m", "1d"). PREFER a
bounded range (both ends) when you know roughly when something happened —
`since` alone fetches every entry from then until now, which on a busy app
is megabytes and gets cut off at the timeout. Range must be <= 35 days.
tail: Search only the last N entries (max 20000) instead of a whole range.
With no since/until/tail, defaults to the last 1000 entries.
source: Search only "stdout", "stderr", or "system".
exclude: Drop lines matching this BEFORE searching, to strip repeated noise.
prefilter: Push `pattern` down to Modal as a server-side substring filter, so
non-matching lines are never fetched. The big lever for huge logs, but it
requires regex=False and leaves `context_lines` showing only other matching
lines — use it to find *where* something is, then re-query that window.
timestamps: Prefix lines with their timestamp. Default True.
timeout_seconds: Max seconds spent fetching logs. Default 30.
env: Modal environment (apps only).
profile: Modal profile for this call only. Defaults to the active profile.
Returns: {match_count (exact, whole log searched), returned (matches actually shown),
returned_blocks, matches (context blocks, matched lines prefixed ">"), excluded_lines,
output_capped}.
Inputs: pattern (required), identifier (required), env, tail, +13 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools have clearly distinct purposes, and the descriptions actively disambiguate the risky pairs: run vs deploy, get_logs vs search_logs, manage_secret vs inspect_secret, manage_volume vs modal_volume_files. The one friction point is the read/write split where reads are funneled through list_modal_resources (volume_files, secrets, app_history) while writes live in separate tools, which an agent may not anticipate without following the cross-references.
Nine of twelve tools follow a clean verb_modal_noun pattern (analyze_modal_costs, deploy_modal_app, get_modal_logs, list_modal_resources, manage_modal_secret, etc.). The only deviation is modal_volume_files, which is noun-only with no verb, making it look like a read tool when it is actually the write surface.
Twelve tools is well within the sweet spot and each maps to a real Modal CLI surface area (apps, containers, volumes, secrets, logs, billing). No obvious filler or redundant tool; the set is scoped to platform operations rather than one narrow action.
Coverage is strong across the Modal lifecycle: deploy/run/stop/rollback apps, exec/stop containers, full volume CRUD plus file transfer, secret create/delete/inspect, log tail and search, billing analysis, and resource discovery. Minor gaps remain (no app deletion, no environment or scheduled-job/cron management, no endpoint/URL management beyond what deploy returns), but these are edge operations an agent can work around or escalate.
Maintenance
Related MCP Connectors
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for interacting with the Supabase platform
Related MCP Servers
- AlicenseBqualityDmaintenanceFacilitates running Python code in a sandbox and generating images using the FLUX model via an MCP server compatible with clients like Goose and the Claude Desktop App.225MIT
- FlicenseDqualityFmaintenanceAn MCP server that allows users to deploy Python scripts to Modal directly from Claude, providing a link to the deployed application that can be shared with others.14-
- AlicenseAqualityDmaintenanceAn MCP server that enables AI agents to interact with Modal, allowing them to deploy apps and run functions in a serverless cloud environment.73MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables LLMs and AI assistants to create, manage, and interact with isolated cloud-based Python environments with GPU support on Modal.com.111MIT