oec.sh

oec.sh MCP 服务

让 AI 助手（Claude Code、Claude Desktop、Cursor 和其他 MCP 客户端）操作你的 oec.sh 组织：查看服务器、项目和环境，读取环境的 Odoo 日志和实时指标，部署、重启、更新模块、创建备份，并跟进任务直至完成。

该服务本身不增加任何权限。每个工具都会使用你的 API 密钥调用一次或两次 oec.sh 公共 API，因此密钥类型（只读或完全访问）、作用范围（整个组织或单个项目）、你的套餐、配额和审计日志都与使用其他任何 API 客户端时完全相同。

**要求：**拥有 Starter 套餐或更高套餐的 oec.sh 组织，以及从控制面板中的 Settings > API Keys 获取的 API 密钥。本地模式需要 Node.js 22 或更高版本。

选择密钥

密钥	前缀	助手可以执行的操作
只读（建议从此开始）	oec_live_ro_	仅限读取工具
完全访问	oec_live_rw_	读取工具和写入工具（部署、重启、创建……）

项目范围的密钥会将助手限制在单个项目中。只要助手只需操作一个项目，就应使用此类密钥。

服务会根据密钥前缀读取密钥类型，并且只提供该密钥可使用的工具。

安装：本地模式（stdio）

MCP 客户端会在你的计算机上启动服务。密钥保留在你的计算机上，只会发送到 api.oec.sh。

Claude Code

claude mcp add oecsh -e OECSH_API_KEY=oec_live_ro_your_key -- npx -y @oecsh/mcp-server

Claude Desktop

将配置添加到 claude_desktop_config.json（Settings > Developer > Edit Config），然后重启 Claude Desktop：

{
  "mcpServers": {
    "oecsh": {
      "command": "npx",
      "args": ["-y", "@oecsh/mcp-server"],
      "env": { "OECSH_API_KEY": "oec_live_ro_your_key" }
    }
  }
}

Cursor

将配置添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "oecsh": {
      "command": "npx",
      "args": ["-y", "@oecsh/mcp-server"],
      "env": { "OECSH_API_KEY": "oec_live_ro_your_key" }
    }
  }
}

不要提交包含密钥的文件。

设置（本地模式）

变量	含义
OECSH_API_KEY	你的 API 密钥。必填。
OECSH_ALLOW	选择启用的工具，以逗号分隔：destructive、backup-download。默认为空。
OECSH_API_URL	API 地址。默认为 https://api.oec.sh/api/public/v1；只有在 oec.sh 支持团队要求时才更改。

托管模式（可流式传输的 HTTP）

https://mcp.oec.sh/mcp。无需安装：客户端会在每个请求的 Authorization 标头中发送 API 密钥，服务仅针对该请求将密钥转发给 API，并且不会留存任何内容。

Claude Code：

claude mcp add --transport http oecsh https://mcp.oec.sh/mcp \
  --header "Authorization: Bearer oec_live_ro_your_key"

Cursor（mcp.json）：

{
  "mcpServers": {
    "oecsh": {
      "url": "https://mcp.oec.sh/mcp",
      "headers": { "Authorization": "Bearer oec_live_ro_your_key" }
    }
  }
}

要在托管模式下启用选择启用的工具，请添加标头 X-OECSH-Allow: destructive（或 backup-download，也可以用逗号分隔，同时添加两者）。

目前，仅通过 OAuth 连接的客户端（例如 claude.ai 网页连接器）尚不能使用托管服务。

托管服务 mcp.oec.sh 会将你的地址传递给 API（它配置了 OECSH_MCP_PROXY_SECRET，见下文），因此 API 对重复拒绝的密钥进行的拦截会按你的地址计数，而不是按服务共享的地址计数。无论采用哪种模式，速率限制都按 API 密钥计算。

工具

每个工具名称都以 oecsh_ 开头。列表工具接受 limit（1 到 100，默认为 20）和 cursor（上一页的 next_cursor），并返回 items、count、total、has_more 和 next_cursor。

读取工具（任意密钥）

工具	功能
oecsh_get_organization	套餐、限制和当前用量
oecsh_list_servers、oecsh_get_server	服务、规格和就绪状态
oecsh_get_server_metrics	你自有服务（非共享服务）的实时 CPU、内存、磁盘和网络指标
oecsh_list_projects、oecsh_get_project	项目
oecsh_list_environments	项目的环境，可按状态筛选
oecsh_get_environment	单个环境及其健康状况和最近一次部署
oecsh_get_runtime_logs	环境中 Odoo 或 PostgreSQL 日志的最新行（最多 1000 行），从其服务实时读取
oecsh_get_environment_metrics	环境容器的实时 CPU 和内存用量，以及磁盘大小
oecsh_list_deployments	环境的部署历史
oecsh_get_task	任意任务的状态和进度
oecsh_wait_for_task	等待任务完成
oecsh_get_task_log	任务的步骤日志和错误
oecsh_list_backups、oecsh_get_backup	环境的备份；单个备份
oecsh_list_webhooks、oecsh_get_webhook、oecsh_list_webhook_deliveries	出站 Webhook 及其近期投递记录
oecsh_list_changelog	oec.sh 发布说明，按时间从新到旧排列；可选仅显示指定版本（since_version）之后或指定日期（since_date）之后的条目
oecsh_list_support_tickets、oecsh_get_support_ticket	组织的支持工单；单个工单及其公开回复（不含内部备注）。需要启用了 Support tickets 的组织范围密钥（Settings > API Keys）

写入工具（全访问权限密钥；均不会删除数据）

工具	功能
oecsh_deploy_environment	拉取分支并重新部署；可更新模块
oecsh_restart_environment、oecsh_start_environment、oecsh_stop_environment	重启、启动、停止
oecsh_quick_update_environment	拉取并重启，更新所有模块或指定模块
oecsh_create_backup	开始手动备份
oecsh_create_project、oecsh_update_project	项目（创建需要组织范围密钥）。更改项目的仓库或 Git 提供方是可选工具
oecsh_create_environment、oecsh_update_environment	环境

oecsh_create_webhook 和 oecsh_rotate_webhook_secret 会返回 Webhook 的签名密钥，因为 API 只会显示一次。此后，密钥会出现在你的对话记录中，工具结果也会说明这一点：如果对话记录会被分享或存储在他人可读取的位置，请在控制面板中轮换密钥（Settings > Webhooks），并自行将新密钥提供给接收方。通过助手轮换密钥也会让新密钥出现在对话记录中。

会启动任务的写入工具会返回 task_id；助手会随后调用 oecsh_wait_for_task。部署、重启、停止、快速更新和两个更新工具都标记为具有破坏性（它们会替换运行中的代码、使站点离线或覆盖设置），因此遵循此提示的客户端会在运行前征求确认；创建工具和启动工具则不会。

选择启用的工具

默认关闭，只有在启用后才可用。每个工具都标记为具有破坏性，这只是一个提示：除非你已将该工具设置为自动批准，否则大多数客户端都会征求你的批准。请勿将这些工具加入客户端的自动批准或允许列表。

这些工具还接受一个 confirm 参数（恢复时为 confirm_environment_name），该参数必须与资源名称完全一致；服务器会在执行任何操作前将其与真实资源进行核对。删除 webhook 或轮换其密钥时，名称是 webhook 的 URL。创建 webhook、测试 webhook 或更改其 URL 时，名称是数据将发送到的主机（对于 https://hooks.example.com/oec，请输入 hooks.example.com）；服务器会从 URL 中读取该主机：在 https://[email protected]/ 中，主机是 other.example。更改 webhook 的其他设置无需 confirm。系统会指示助手向你询问该名称，但助手也可以通过列表工具读取名称，因此仅凭该参数无法证明名称是你输入的。因此，如果你的客户端支持 MCP elicitation（可显示服务器提供的表单），服务器还会在客户端自己的提示中要求你输入名称，并说明操作和资源；只有你接受且名称匹配时，操作才会继续。拒绝或输入其他内容都不会产生任何变化。不支持 elicitation 的客户端以及托管服务器（不保留会话，因此无法询问）仅依赖 confirm 参数。

选择启用	工具	密钥
destructive	oecsh_delete_environment、oecsh_delete_project、oecsh_delete_webhook、oecsh_rotate_webhook_secret、oecsh_revoke_api_key、oecsh_reinitialize_modules、oecsh_restore_backup、oecsh_update_project_repository、oecsh_create_webhook、oecsh_update_webhook、oecsh_test_webhook	完整访问权限（撤销密钥和删除项目：按组织范围授权）
backup-download	oecsh_get_backup_download_links（指向完整数据库转储的链接，默认有效期为 5 分钟，最长 60 分钟）	任意

创建、更改和测试 webhook 均需选择启用，因为 webhook 会将 oec.sh 数据发送到其指定的任意 HTTPS URL，而且测试会立即发送：其他人写入结果中的文本（例如 Odoo 日志行）可能会要求助手将 webhook 指向他们自己的地址。更改项目的仓库或 Git 提供商（oecsh_update_project_repository）出于同样的原因也需选择启用：此后每次部署都会在你的服务器上运行新仓库中的代码，而且 Git 提供商决定你的组织 Git 令牌会发送到哪个主机。oecsh_update_project 会更改项目的其他所有内容。分支名称（branch、default_branch）必须是实际的分支名称：服务器会拒绝 ref 路径（例如 refs/...、pull/... 或 merge-requests/...）、裸提交 ID 以及以 - 开头的名称，因此部署无法获取来自 fork 的拉取请求中的代码。

oecsh_get_backup_download_links 会返回一条警告：任何持有链接的人都能在链接过期前下载整个数据库，而且这些链接现在已出现在对话记录中。

使用只读密钥时，服务器提供 19 个工具（启用 backup-download 后为 20 个）。使用完整访问权限密钥时，服务器提供 29 个工具；启用 destructive 后为 40 个，同时启用两个选项后为 41 个。

oecsh_restore_backup 会用同一环境的已完成备份覆盖该环境的数据库和文件（首先会为当前数据创建安全备份），并返回一个任务供你跟踪。恢复或获取下载链接时需要输入的名称，是环境当前的名称；对于已停止或损坏、因而未被 API 列出的环境，则使用备份中记录的名称（参见 oecsh_get_backup）。恢复到其他环境的操作仍需在控制面板中进行。

此服务器不提供服务器注册令牌。

限制

• 每个 API 请求都会计入密钥的速率限制：每分钟 120 次读取和 20 次写入，分别计数。
• 大多数工具会发出一到两个 API 请求。oecsh_get_backup_download_links 和 oecsh_restore_backup 会发出三个请求，其他每个已确认的破坏性工具会发出两个请求（会先读取资源以检查名称）；创建 webhook 或更改其 URL 除外，这两项会检查给定 URL 中的主机，并发出一个请求。
• oecsh_get_runtime_logs、oecsh_get_environment_metrics 和 oecsh_get_server_metrics 每次调用都会访问你的服务，因此 API 对每个环境或服务的这类请求限制为每分钟 6 次。
• oecsh_wait_for_task 在前 30 秒每 5 秒轮询一次任务，之后每 10 秒轮询一次，并且使用的读取次数不会超过 API 报告的密钥读取限制的五分之一（如果限制为每分钟 20 次，则每 15 秒轮询一次）。每次调用最多等待 50 秒，因为许多客户端会在工具调用超过 60 秒后放弃；在托管模式下最多等待 45 秒；任务仍在运行时，助手会再次调用该工具。在本地模式下，如果客户端请求进度说明（此时每次轮询后都会发送一条），或助手传入更长的 timeout_seconds，则最多等待 10 分钟。
• 达到限制时，工具会告知需要等待多久，时间取自 API 的 Retry-After（如果没有，则等待到下一个整分钟）。等待时间不超过 10 秒时会自动重试一次；如果等待时间在 oecsh_wait_for_task 的时间限制内，该工具会等待限制解除后再继续。
• 如果某个操作（部署、重启、恢复……）的响应在网络中丢失，服务会使用相同的幂等键再次请求一次，因此 API 会返回第一次操作的响应，而不会重复执行操作。
• oecsh_get_task_log 最多返回任务自身日志的 1000 行；oecsh_get_runtime_logs 返回 Odoo 或 PostgreSQL 日志。两者都会截取最新的 60,000 个字符（并将 truncated 设为 true），确保单次响应不超出客户端可接受的范围。
• 运行中、已停止、已暂停和出错的环境都会显示。已删除的环境会返回“未找到”；其备份和任务仍可读取。
• 每个 API 请求的超时时间为 30 秒。托管服务接受最大为 1 MB 的请求正文。

安全说明

• 每次调用前都会检查密钥格式是否正确；密钥只会通过 Authorization 标头发送到配置的 API，并会从所有输出、错误和日志行中移除。服务器绝不会打印密钥。
• API 地址必须使用 https（仅允许对 localhost 使用普通 http），且服务器绝不跟随重定向，因此密钥不会以明文发送，也不会被重放到其他地址。
• 在托管模式下，API 地址由服务器固定；客户端无法将你的密钥指向其他主机。格式不正确的密钥会在读取请求正文前被拒绝；API 刚刚拒绝过的密钥会在本地被拒绝 5 分钟。API 在 10 个密钥被拒后会封禁一个地址 15 分钟，因此，对于服务器尚未确认可用的密钥，工具调用最多会遭遇 6 次可能的拒绝，之后会等到 API 的计数重置；近期验证成功的密钥不受限制。如果服务器向 API 传递调用方地址（OECSH_MCP_PROXY_SECRET），计数会按调用方地址分别记录；否则，计数会在整个服务器范围内共用，因为此时 API 看到的所有托管用户都来自服务器的同一个地址。内存中只会保存密钥的哈希值。每个请求只携带一条 JSON-RPC 消息（不接受批量请求）。
• 助手传入的每个 ID 都会先检查是否为 UUID，再放入请求。
• 助手发起的备份只会保存到你组织自己的存储中；API 会拒绝属于其他组织的存储位置。
• 结果中的名称、备注、分支名称和日志文本都属于你的数据。它们会作为数据返回，服务器会告知助手不要遵循其中的指令。包含他人编写文本的结果（运行时日志和任务日志、任务错误消息、部署历史记录、备份备注和快照）会在这些文本前附带一个 notice 字段，说明这一点；这些工具也会标记为开放世界。Webhook 交付列表不会包含接收 URL 返回的正文，因为该 URL 的运营者可以编写该内容。
• 在托管模式下，每个密钥最多同时运行 3 次工具调用，每个调用方地址最多同时运行 10 次；超出时会报错“工具调用过多”。此模式下的错误消息会使用“oec.sh API”作为名称，而不会透露服务器使用的地址；同时会省略非 API 自身 JSON 中的响应内容。
• 切勿将 API 密钥粘贴到聊天中。助手不需要密钥：服务器会从配置中读取，而输入到聊天中的任何内容都会保留在对话记录里。
• MCP 客户端配置文件（claude_desktop_config.json、~/.claude.json、mcp.json 等）会以明文保存密钥。请勿将它们纳入版本控制、与他人共享的备份或屏幕共享内容中。
• 使用 Claude Code 时，不要通过 --scope project 添加服务器：这会将密钥写入项目中的 .mcp.json，而该文件通常需要提交到版本控制。请使用默认的（本地）范围或 --scope user。
• 默认关闭具有破坏性和敏感性的工具。建议优先使用只读、限定项目范围的密钥，仅在助手需要进行更改时才提供完全访问权限的密钥。
• 如果密钥泄露，请立即撤销：设置 > API 密钥。

自行运行 HTTP 服务

docker build -t oecsh-mcp ./mcp-server
docker run -p 127.0.0.1:8080:8080 -e OECSH_MCP_ALLOWED_HOSTS=localhost oecsh-mcp

源站必须只能通过你的代理访问（对于 mcp.oec.sh：先经过 Cloudflare，再经过 Traefik）。将端口发布到回环地址，或仅发布到代理所在的 Docker 网络，切勿绑定到公共网络接口：服务传递给 API 的调用方地址及其按地址设置的限额，都依赖前置代理。

在生产环境中，将 OECSH_MCP_ALLOWED_HOSTS 设置为公共主机名（例如 mcp.oec.sh）。如果绑定地址不是回环地址，且未设置 OECSH_MCP_ALLOW_ANY_HOST=1，服务将拒绝启动。

变量	默认值	含义
OECSH_MCP_HOST	127.0.0.1（镜像中为 0.0.0.0）	绑定地址
OECSH_MCP_PORT	8080	端口
OECSH_API_URL	https://api.oec.sh/api/public/v1	接收密钥的 API。必须使用 https，但 localhost 除外
OECSH_API_ALLOW_HTTP	（关闭）	设为 1 后，允许 OECSH_API_URL 使用非回环地址上的普通 http；仅适用于同一内部网络上的 API
OECSH_MCP_MAX_BODY_BYTES	1048576	请求正文的最大大小
OECSH_MCP_ALLOWED_HOSTS	（无）	允许的主机名，以逗号分隔。绑定到回环地址时，始终允许 localhost、127.0.0.1 和 [::1]，并拒绝其他所有 Host。绑定到其他地址时必须设置。
OECSH_MCP_ALLOW_ANY_HOST	（关闭）	绑定到非回环地址时，设为 1 可接受任何 Host 标头（此时 DNS 重绑定防护仅依赖 Origin 检查）
OECSH_MCP_ALLOWED_ORIGINS	（无）	允许的浏览器来源。不影响不带 Origin 标头的请求。
OECSH_MCP_PROXY_SECRET	（无）	至少包含 32 个可打印 ASCII 字符且不含空格的密钥（例如 openssl rand -hex 32），与 API 共享。设置后，每个 API 请求都会携带 X-OECSH-MCP-Proxy: <secret> 和 X-OECSH-Client-IP: <caller's address>，API 会将被拒绝的密钥计入调用方，而不是此服务。该密钥只发送到 OECSH_API_URL，不会记录日志，也不会返回。未设置时，不会发送这两个标头。先在 API 上将 PLATFORM_MCP_PROXY_SECRET 设置为相同的值：如果 API 上的该值为空或不匹配，API 会忽略这些标头，而此服务无法得知，因此所有托管用户仍会共用同一个计数。此功能仅适用于你配置的 API；指向 api.oec.sh 的可自托管服务应将其留空。
OECSH_MCP_CLIENT_IP_HEADER	cf-connecting-ip	包含调用方地址的请求标头，由此服务的前置代理设置。只有当前置本地代理的跃点（X-Forwarded-For 中最后一项，由 Traefik 追加；仅当连接来自私有地址或受信任的代理时才读取）位于 Cloudflare 公布的地址范围内，或位于 OECSH_MCP_TRUSTED_PROXIES 中时，才会信任该标头。否则，或当其值不是单个 IPv4 或 IPv6 地址时，将该跃点视为调用方地址。地址会以统一格式传递（IPv6 压缩表示，IPv4 映射的 IPv6 地址表示为 IPv4）。
OECSH_MCP_TRUSTED_PROXIES	（无）	额外的受信任代理，以逗号分隔的地址或 CIDR 范围表示；其客户端地址标头会被信任，并且这些代理可以直接连接到服务。

端点：POST /mcp（MCP，无状态，JSON 响应）和 GET /healthz。请将其置于终止 TLS 并限制每个地址的连接数的代理之后。

开发

cd mcp-server
npm install
npm run build
npm test
npx @modelcontextprotocol/inspector -e OECSH_API_KEY=oec_live_ro_... node dist/stdio.js

此软件包不依赖 oec.sh 仓库的其他部分。

许可

MIT，详见 LICENSE。版权所有 (c) 2026 OpenEduCat Inc. 如需报告安全问题，请参阅 SECURITY.md。

Odoo 是 Odoo S.A. 的商标。oec.sh 与 Odoo S.A. 无关联。