MCP Modal Server

io.github.george-bobby由 GitHub 帳號 george-bobby 發布v1.0.1更新於 Nov 14, 2026

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

概覽

AI 產生的概覽

透過呼叫本機 Modal CLI,讓助手在 MCP 用戶端管理 Modal 應用程式、容器、磁碟區、密鑰、日誌與費用。

可以做什麼
  • 列出應用程式、部署歷史、容器、磁碟區、磁碟區內檔案、密鑰、環境與設定檔
  • 取得或持續追蹤應用程式與容器日誌,並依關鍵字搜尋並回傳上下文
  • 部署應用程式以取得可用的端點網址,或單次執行函式或進入點並收集輸出
  • 停止或回復應用程式,在容器內執行指令或停止容器
  • 建立、刪除或重新命名磁碟區,並上傳、下載、複製或刪除磁碟區內檔案
  • 建立或刪除密鑰、列出密鑰的鍵名,並依應用程式、環境或資源統計費用
適用情境
適合已在 Modal 上執行工作負載、希望助手代為部署並驗證應用程式、依日誌與容器排查故障、清理閒置資源,或追查費用上升來源的情境。
執行需求
以 uvx 在本機執行,需要 Python 3.11+ 與 uv,以及已透過 modal setup 登入的 Modal CLI 1.5+(憑證存於 ~/.modal.toml)。被部署或執行的應用程式需使用 uv,且其虛擬環境中已安裝 modal。選用環境變數 MCP_MODAL_ALLOWED_LOCAL_PATHS 與 MCP_MODAL_MAX_OUTPUT_CHARS 可限制本機路徑與輸出長度。
安裝前請注意
此伺服器擁有與你的 Modal 登入相同的權限。部署與執行工具會執行本機 Python 程式碼,容器 exec 可執行任意指令,磁碟區檔案工具可上傳或覆寫本機檔案,建立密鑰時可從本機 dotenv 或 JSON 檔案讀取內容寫入 Modal 密鑰。建議對寫入類工具保留人工確認;刪除磁碟區無法復原,部署後的端點會持續上線且可被分享。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 MCP Modal Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

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

來源:README.md,提交 b2a85e1

工具

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

輸入參數envaction必填profileversionapp_identifier必填

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

輸入參數action必填commandprofilecontainer_id必填timeout_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.

輸入參數appendviewstarttop_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}.

輸入參數envtagnameprofilestrategystream_logsabsolute_path_to_app必填

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

輸入參數envdetachprofilefunction_nametimeout_secondsabsolute_path_to_app必填

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

輸入參數envtailsinceuntilfollowsourcetargetprofileidentifier必填timestampstimeout_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

輸入參數envtailregexsinceuntilsourcetargetexcludepattern必填profileprefilteridentifier必填另有 5 個

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.

輸入參數envnamepathprofileresource必填

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.

輸入參數envforceaction必填profilefrom_jsonkey_valuesfrom_dotenvsecret_name必填

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.

輸入參數envimageprofilesecret_name必填timeout_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}.

輸入參數envaction必填profilenew_namevolume_name必填

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.

輸入參數envforcepathsaction必填profilerecursivelocal_pathremote_pathvolume_name必填

版本歷史

2
  1. v1.0.1最新Nov 13, 2026
  2. v0.5.0Sep 16, 2026

評分

已滿足適用檢查項的 90%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分
  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分