MCP Modal Server

io.github.george-bobbyPublished by GitHub account george-bobbyv1.0.1Updated Nov 14, 2026

MCP server for managing Modal apps, containers, volumes, and secrets.

Overview

AI-generated overview

Manages Modal apps, containers, volumes, secrets, logs and costs from an MCP client by driving the local Modal CLI.

What you can do
  • List apps, app history, containers, volumes, volume files, secrets, environments and profiles
  • Fetch or follow app and container logs, and grep them with surrounding context
  • Deploy an app to get live endpoint URLs, or run a function or entrypoint once and collect output
  • Stop or roll back an app, run commands in or stop a container
  • Create, delete or rename volumes and upload, download, copy or remove files in them
  • Create or delete secrets, list a secret's key names, and rank spend by app, environment or resource
When to use it
Useful when you already run workloads on Modal and want an assistant to deploy and verify apps, debug failures from logs and containers, clean up idle resources, or trace a cost increase without switching to the dashboard.
Requirements
Runs locally via uvx, so Python 3.11+ and uv are needed, plus Modal CLI 1.5+ logged in through modal setup (credentials in ~/.modal.toml). Apps being deployed or run must use uv with modal installed in their virtualenv. Optional env vars MCP_MODAL_ALLOWED_LOCAL_PATHS and MCP_MODAL_MAX_OUTPUT_CHARS tune path limits and output size.
Before you install
The server can do anything your Modal login can. Deploy and run tools execute local Python code; container exec runs arbitrary commands; volume file tools can upload or overwrite local files; secret creation can read a local dotenv or JSON file into a Modal secret. Keep write tools behind approval prompts. Volume deletion is irreversible, and deployed endpoints stay live and shareable.

Installation

In SourceWeft

  1. Open MCP Modal Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Modal MCP Server

[PyPI] [Python] [Tests] [License]

Manage Modal from Claude Code or any MCP client: apps, containers, logs, volumes, secrets and costs, plus deploying and running your own Modal apps.

It runs your local modal CLI, so it uses the profile and credentials already on your machine. There are no extra tokens to manage.

[Modal MCP server] [mcp-modal MCP server]

Quick start

  1. Log in to Modal once (this writes ~/.modal.toml):

    bash
    modal setup
  2. Add the server to Claude Code:

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

    Or share it with your team through a .mcp.json in the project root:

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

uvx caches a tool after its first run, so a plain uvx mcp-modal never updates. @latest checks PyPI on every launch. Pin an exact version ([email protected]) when every machine must run the same build.

Requirements

  • Python 3.11+ and uv
  • Modal CLI 1.5+, logged in with modal setup
  • To deploy or run an app, that app's project must use uv and have modal installed in its virtualenv

Tools

ToolWhat it does
list_modal_resourcesRead-only lookup of apps, app_history, containers, volumes, volume_files, secrets, environments or profile
get_modal_logsFetch or follow logs for an app or a container
search_modal_logsGrep logs and return each match with surrounding lines
analyze_modal_costsRank spend by app, environment or resource, explain a cost spike, or show the bill and rates
deploy_modal_appmodal deploy, returning the live endpoint URLs
run_modal_appmodal run a function or entrypoint and collect its output
manage_modal_appStop an app, or roll it back to an earlier version
manage_modal_containerRun a command in a container, or stop it
manage_modal_volumeCreate, delete or rename a volume
modal_volume_filesUpload, download, copy or remove files in a volume
manage_modal_secretCreate or delete a secret (values are redacted from all output)
inspect_modal_secretList the key names inside a secret, never its values (starts a short container)

Each tool's full arguments are in its MCP schema, so your client shows them. Common ones:

  • env targets a Modal environment. Leave it out to use the profile's default.
  • profile runs a single call against another profile in ~/.modal.toml, for example list_modal_resources(resource="apps", profile="work"). Your default profile is not changed.

Tips:

  • On a busy app, give log tools both since and until. since on its own fetches everything from then until now. search_modal_logs(prefilter=True) filters on Modal's side when the logs are too large to fetch.
  • Logs only contain stdout, stderr and system output. Crash events shown on the Modal dashboard (such as "… exited with …") are not log lines, so they won't appear here.
  • There is no modal serve tool, because its endpoints stop when the command returns. Use deploy_modal_app to get an endpoint that stays up.

Prompts

Four ready-made workflows. In Claude Code they appear as /mcp__mcp-modal__<name>:

  • debug_modal_app: work out why an app is failing, from logs, containers and deploy history
  • deploy_and_verify: deploy an app, then check it is actually healthy
  • review_modal_account: find idle apps, stray containers and orphaned volumes or secrets
  • investigate_modal_costs: trace a cost increase down to the app, resource and hour

Security

The server can do anything your Modal login can. Let your client auto-approve the four read-only tools (list_modal_resources, get_modal_logs, search_modal_logs, analyze_modal_costs), and keep the rest behind an approval prompt. In particular:

  • deploy_modal_app and run_modal_app execute local Python code.
  • modal_volume_files can upload any local file (put) or overwrite one (get with force).
  • manage_modal_secret with from_dotenv or from_json reads a local file and stores its contents in a Modal secret.
  • manage_modal_container with exec runs arbitrary commands in a container.

Every tool declares MCP read-only and destructive hints so clients can tell these apart. Names and paths are passed after -- or as --option=value, so a value starting with - can never act as a CLI flag.

Configuration

Set these in the env block of your MCP client config:

VariableDefaultEffect
MCP_MODAL_ALLOWED_LOCAL_PATHSunset (no limit):-separated directories that modal_volume_files and manage_modal_secret may read from or write to
MCP_MODAL_MAX_OUTPUT_CHARS40000Character limit per text field in a response. 0 turns the limit off

When output is cut, the response sets output_capped: true and keeps both the start and the end of the text.

Responses

Every tool returns JSON with success. On failure it also has error, plus the command that ran and its stdout/stderr when available. On success:

  • list_modal_resources returns its items under apps, history, containers, volumes, contents, secrets or environments. Lists longer than 200 items are cut, and omitted_items says how many were left out. resource="profile" returns active_profile and profiles instead.
  • Actions return message, command, stdout and stderr.
  • Logs and runs return logs or output. truncated: true means the command was still running when the timeout hit.
  • Log search returns match_count (an exact count over the whole fetched log) and matches, which are line-numbered context blocks with each matching line marked >.

Source: README.md at commit b2a85e1

Tools

12

manage_modal_app

Stop or roll back a Modal app

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

Parametersenvactionrequiredprofileversionapp_identifierrequired

manage_modal_container

Run a command in, or stop, a Modal container

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

Parametersactionrequiredcommandprofilecontainer_idrequiredtimeout_seconds

analyze_modal_costs

Analyze Modal costs

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.

Parametersappendviewstarttop_nperiodprofiletimezonetag_namesresolutionenvironment

deploy_modal_app

Deploy a Modal app

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

Parametersenvtagnameprofilestrategystream_logsabsolute_path_to_apprequired

run_modal_app

Run a Modal function

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

Parametersenvdetachprofilefunction_nametimeout_secondsabsolute_path_to_apprequired

get_modal_logs

Read Modal logs

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

Parametersenvtailsinceuntilfollowsourcetargetprofileidentifierrequiredtimestampstimeout_seconds

search_modal_logs

Search Modal logs

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

Parametersenvtailregexsinceuntilsourcetargetexcludepatternrequiredprofileprefilteridentifierrequired+5 more

list_modal_resources

List Modal resources

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.

Parametersenvnamepathprofileresourcerequired

manage_modal_secret

Create or delete a Modal secret

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.

Parametersenvforceactionrequiredprofilefrom_jsonkey_valuesfrom_dotenvsecret_namerequired

inspect_modal_secret

Inspect a Modal secret's key names

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.

Parametersenvimageprofilesecret_namerequiredtimeout_seconds

manage_modal_volume

Create, delete or rename a Modal volume

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

Parametersenvactionrequiredprofilenew_namevolume_namerequired

modal_volume_files

Move files in a Modal volume

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.

Parametersenvforcepathsactionrequiredprofilerecursivelocal_pathremote_pathvolume_namerequired

Version history

2
  1. v1.0.1LatestNov 13, 2026
  2. v0.5.0Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts