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 分