sauce-api-mcp

Sauce Labs MCP 服务

一个模型上下文协议（MCP）服务，可与 Sauce Labs 测试平台全面集成。该 软件包包含两个互补的 MCP 服务，可让 AI 助手通过自然语言对话与 Sauce Labs 的设备云交互、管理 测试任务、分析构建并监控测试基础设施。

提示

想要使用托管且功能更丰富的选项？ Sauce MCP 是 Sauce Labs 官方托管的 MCP 服务，地址为 https://mcp.saucelabs.com。无需安装或更新，并且 提供比此软件包更丰富的工具集，包括实时控制真实设备（点按、输入、截图、安装/启动应用）、网络捕获，以及由 AI 驱动的测试用例编写、执行和排期。请参阅 连接 AI 客户端了解设置说明。

服务

此软件包提供两个独立的 MCP 服务，分别针对不同的使用场景进行了优化：

sauce-api-mcp（核心服务）——全面集成 Sauce Labs API，用于账户管理、设备发现、任务 分析、构建、存储和隧道管理。

sauce-api-mcp-rdc（RDC 服务）——专注于真实设备云（RDC）的服务。启动时使用 FastMCP 和 OpenAPIProvider，从 Sauce Labs 官方 OpenAPI 规范动态生成 MCP 工具， 因此无需更改代码，工具集也始终保持最新。还包含一小组手写工具，用于特殊处理的端点（如二进制载荷、会话生命周期、应用安装轮询）。

两个服务可以同时配置在你的大模型客户端中，以全面覆盖 Sauce Labs 功能。

功能

🚀 核心功能

• 账户管理：查看账户详情、团队信息和用户权限
• 设备云访问：浏览 300 多台真实设备（iOS、Android）和虚拟机
• 测试任务管理：获取近期任务、分析测试结果并调试故障
• 构建监控：跟踪构建状态、查看任务集合并分析测试套件
• 存储管理：管理已上传的应用和测试产物
• 隧道监控：检查 Sauce Connect 隧道状态和配置

🔧 高级功能

• 实时设备状态：监控各数据中心的设备可用性和使用情况
• 跨平台测试：支持虚拟设备云（VDC）和真实设备云（RDC）
• 测试分析：提供详细的任务信息，包括日志、视频和性能指标
• 团队协作：支持多团队并提供适当的访问控制
• 动态 RDC API：sauce-api-mcp-rdc 在启动时从 OpenAPI 规范自动发现最新的 RDC v2 端点； 网络不可用时则使用缓存的规范作为备用
• 响应整形：自动截断大型 API 列表响应，以控制大模型上下文预算（ 可通过 SAUCE_MCP_MAX_RESPONSE_ITEMS 配置）
• 文件安全：设备上的文件推送/拉取操作仅限于 ~/.sauce-mcp/files/，以防止路径遍历

前置条件

• Python 3.10+
• pip
• 拥有 API 访问权限的 Sauce Labs 账户
• Claude Desktop、Gemini CLI、Goose 或其他兼容 MCP 的大模型客户端

安装

从 PyPI 安装软件包：

pip install sauce-api-mcp

这会安装两个服务，并注册它们的命令行入口：

• sauce-api-mcp — 核心服务
• sauce-api-mcp-rdc — RDC OpenAPI 服务

验证安装：

which sauce-api-mcp
which sauce-api-mcp-rdc

大模型客户端配置

Claude Desktop（Mac / Linux / Windows）

1. 找到 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 找到 Python 安装目录中的 bin 目录：

   python3 -c "import sys; print(sys.prefix + '/bin')"
   

3. 将两个服务都添加到配置中：

   {
     "mcpServers": {
       "sauce-api-mcp-core": {
         "command": "/path/to/bin/sauce-api-mcp",
         "env": {
           "SAUCE_USERNAME": "your-sauce-username",
           "SAUCE_ACCESS_KEY": "your-sauce-access-key"
         }
       },
       "sauce-api-mcp-rdc": {
         "command": "/path/to/bin/sauce-api-mcp-rdc",
         "env": {
           "SAUCE_USERNAME": "your-sauce-username",
           "SAUCE_ACCESS_KEY": "your-sauce-access-key"
         }
       }
     }
   }
   

4. 重启 Claude Desktop 以加载服务。

Gemini CLI

添加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "sauce-api-mcp-core": {
      "command": "/path/to/bin/sauce-api-mcp",
      "env": {
        "SAUCE_USERNAME": "your-sauce-username",
        "SAUCE_ACCESS_KEY": "your-sauce-access-key"
      }
    },
    "sauce-api-mcp-rdc": {
      "command": "/path/to/bin/sauce-api-mcp-rdc",
      "env": {
        "SAUCE_USERNAME": "your-sauce-username",
        "SAUCE_ACCESS_KEY": "your-sauce-access-key"
      }
    }
  }
}

Goose

添加到 ~/.config/goose/config.yaml：

sauce-api-mcp-core:
  cmd: /path/to/bin/sauce-api-mcp
  description: Sauce Labs MCP (Core)
  enabled: true
  envs:
    SAUCE_USERNAME: your-sauce-username
    SAUCE_ACCESS_KEY: your-sauce-access-key
  type: stdio

sauce-api-mcp-rdc:
  cmd: /path/to/bin/sauce-api-mcp-rdc
  description: Sauce Labs MCP (RDC)
  enabled: true
  envs:
    SAUCE_USERNAME: your-sauce-username
    SAUCE_ACCESS_KEY: your-sauce-access-key
  type: stdio

环境变量（替代方案）

除了将凭据添加到配置文件中，也可以将它们导出为环境变量：

export SAUCE_USERNAME="your-sauce-username"
export SAUCE_ACCESS_KEY="your-sauce-access-key"

然后从配置中省略 env 块。两个服务都会自动获取这些变量。

配置

必需的环境变量

变量	描述
SAUCE_USERNAME	你的 Sauce Labs 用户名
SAUCE_ACCESS_KEY	你的 Sauce Labs 访问密钥（可在账户设置中找到）

可选的环境变量

变量	默认值	描述
SAUCE_REGION	US_WEST	数据中心区域：US_WEST、US_EAST、EU_CENTRAL
SAUCE_MCP_MAX_RESPONSE_ITEMS	100	截断前返回的最大列表项数（RDC 服务）

获取 Sauce Labs 凭据

1. 登录你的 Sauce Labs 账户
2. 前往 Account → User Settings
3. 复制你的 Username 和 Access Key

安装故障排除

“Command not found: sauce-api-mcp”

入口脚本不在你的 PATH 中。请使用完整路径：

python3 -m pip list | grep sauce-api-mcp
python3 -c "import sys; print(sys.prefix + '/bin/sauce-api-mcp')"

MCP 客户端中出现 “ENOENT: no such file or directory”

MCP 客户端使用了不同的 Python 环境。解决方案：

1. 使用完整绝对路径（推荐）——使用 python3 -c "import sys; print(sys.prefix + '/bin/sauce-api-mcp')" 打印出的路径更新配置，而不是只使用 which sauce-api-mcp
2. 模块调用（备用方案）：

   "command": "python3",
   "args": ["-m", "sauce_api_mcp.main"]
   

示例提示词

• “显示我最近的测试失败情况”
• “查找可用的 iPhone 16 设备”
• “分析我最新构建的性能”
• “在 Samsung 设备上开启会话并安装我的应用”
• “我现在有哪些隧道正在运行？”

可用工具

核心服务（sauce-api-mcp）

账户与组织

工具	描述
get_account_info	获取当前用户的账户信息
lookup_users	查找组织中的用户
get_user	获取用户详细信息
lookup_teams	查找组织中的团队
get_team	获取团队详情
list_team_members	列出指定团队的所有成员
lookup_service_accounts	列出服务账户
get_service_account	获取服务账户详情
get_my_active_team	获取已认证用户的活跃团队

设备管理

工具	描述
get_devices_status	列出所有设备及其当前状态
get_specific_device	获取特定设备的详细信息
get_private_devices	列出账户可用的专用设备

测试任务

工具	说明
get_recent_jobs	获取最近的测试任务
get_job_details	获取特定任务的详细信息
get_real_device_jobs	列出真实设备上的活动任务
get_specific_real_device_job	获取特定真实设备任务的详细信息
get_specific_real_device_job_asset	下载任务资源（日志、视频、屏幕截图）

构建

工具	说明
lookup_builds	根据筛选条件搜索构建
get_build	获取特定构建的详细信息
get_build_for_job	获取与任务关联的构建
lookup_jobs_in_build	列出构建中的所有任务

存储

工具	说明
get_storage_files	列出已上传的应用文件
get_storage_groups	列出应用存储组
get_storage_groups_settings	获取存储组的设置
upload_file_to_storage	将应用文件上传到 Sauce Storage
update_storage_group_settings	更新应用组设置（重新签名、插桩等）

隧道

工具	说明
get_tunnels_for_user	列出活动的 Sauce Connect 隧道
get_tunnel_information	获取特定隧道的详细信息
get_current_jobs_for_tunnel	查看有多少任务正在使用隧道
get_tunnel_version_downloads	获取 Sauce Connect 各版本的下载 URL

测试资源与日志

工具	说明
get_test_assets	获取 VDC 任务的测试产物
get_log_json_file	获取 VDC 任务的结构化测试执行日志
get_network_har_file	获取经过筛选的 HAR 网络捕获数据
filter_har_data	高效筛选缓存的 HAR 数据（无需重新下载）

RDC 服务（sauce-api-mcp-rdc）

RDC 服务会根据 Sauce Labs RDC v2 OpenAPI 规范自动生成工具。随着规范演进，完整工具列表也会有所变化，但以下类别始终存在。

会话管理

工具	说明
createSession	分配一台真实设备并返回一个处于 ACTIVE 状态的会话。轮询直至会话变为 ACTIVE 或超时（约 55 秒）
listSessions	列出当前设备会话，并可选择性地进行筛选
deleteSession	关闭会话并将设备释放回资源池
get_session_details	获取特定会话的完整详细信息

设备发现

工具	描述
listDevices	浏览完整的设备目录，并按操作系统／型号筛选
list_device_status	获取设备的实时可用状态

应用管理

工具	描述
installApp	在设备上启动应用安装（返回安装 ID）
waitForAppInstallation	轮询安装状态——重复调用，直到状态为 FINISHED
launchApp	启动已安装的应用
uninstallApp	从设备中移除应用
list_app_installations	列出正在进行或最近的应用安装
install_app_from_storage	从 Sauce Storage 安装应用

设备交互

工具	描述
take_screenshot	截取当前设备屏幕
open_url_or_deeplink	在设备上打开 URL 或深层链接
execute_shell_command	运行 adb shell 命令（Android）
applyDeviceSettings	更改设备设置（方向、区域设置等）

文件操作

工具	描述
push_file_to_device	将本地文件上传到设备（仅限 ~/.sauce-mcp/files/）
pull_file_from_device	从设备下载文件
listFiles	列出设备目录中的文件
removeFile	删除设备上的文件
statFile	获取设备上文件或目录的元数据

网络与代理

工具	描述
proxy_http	通过设备代理转发 HTTP 请求
startNetworkCapture / stopNetworkCapture	捕获网络流量
setNetworkProfile / setNetworkConditions	模拟网络条件
listNetworkProfiles	列出可用的网络配置文件
resetNetworkConditions	恢复正常连接

Appium

工具	描述
startAppiumServer	启动与设备共置的托管 Appium 服务
getAppiumServerStatus	检查 Appium 是否正在运行，并获取其端点 URL
listAppiumVersions	列出可用的 Appium 版本
launchWebDriverAgent	在 iOS 设备上启动 WDA
getWebDriverAgentStatus	检查 WDA 状态

开发环境设置

先决条件

• Python 3.10+
• uv 包管理器
• Git

克隆和设置

git clone https://github.com/saucelabs/sauce-api-mcp.git
cd sauce-api-mcp
uv sync

这会创建虚拟环境，并以可编辑模式安装所有依赖项（包括测试附加项）。

项目结构

sauce-api-mcp/
├── src/sauce_api_mcp/
│   ├── main.py              # Core server — hand-written MCP tools
│   ├── rdc_dynamic.py       # RDC server — OpenAPIProvider + hand-written tools
│   ├── models.py            # Pydantic response models
│   └── shared/              # Shared utilities
├── tests/                   # Test suite
├── server.json              # MCP Registry manifest
├── pyproject.toml           # Package config, entry points, PSR release config
└── uv.lock                  # Locked dependencies

在本地运行服务

uv run sauce-api-mcp
uv run sauce-api-mcp-rdc

两者都会打印 Error: This server is not meant to be run interactively——这是预期行为（它们通过 stdio 与 MCP 客户端通信，而不是与终端通信）。

若要让 MCP 客户端连接到本地开发检出版本：

{
  "command": "/path/to/sauce-api-mcp/.venv/bin/sauce-api-mcp"
}

运行测试

测试分为三组：

# Integration tests (no live credentials required)
uv run pytest -m "not live and not slow"

# Live tests (require SAUCE_USERNAME + SAUCE_ACCESS_KEY)
uv run pytest -m "live and not slow"

# Slow tests (allocate real devices — takes minutes)
uv run pytest -m "slow"

# Full suite
uv run pytest

添加依赖项

uv add httpx
uv add --dev pytest-asyncio

CI / 发布工作流

持续集成

每个以 main 为目标分支的拉取请求都会通过 build.yml 依次运行三个作业：

1. test — 在 Python 3.10、3.11、3.12 上运行集成测试（并行）
2. test-live — 在 Python 3.12 上运行实时测试（在 test 之后）
3. test-slow — 在 Python 3.12 上运行慢速测试（在 test-live 之后）

发布

通过 GitHub Actions 中的 Release 工作流（publish.yml）手动触发发布：

1. 前往 Actions → Release → Run workflow
2. 选择发布类型：patch、minor、major 或 prerelease
3. 对于预发布版本，可选择设置标记（alpha、beta、rc）

随后，工作流会：

• 使用 python-semantic-release 更新 pyproject.toml 和 server.json 中的版本号
• 创建 v* git 标签和 GitHub Release，并自动生成变更日志
• 将稳定版发布到 PyPI 和 MCP Registry
• 仅将预发布版（alpha/beta/rc）发布到 TestPyPI

参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

获取帮助

• Sauce Labs 文档：docs.saucelabs.com
• API 参考：docs.saucelabs.com/dev/api
• 支持：通过账户控制面板联系 Sauce Labs 支持团队
• GitHub 问题：报告错误或请求新功能

变更日志

如需查看完整的发布和变更历史，请参阅 GitHub Releases 页面。

v1.1.0

• 将 sauce-api-mcp 和 sauce-labs-mcp（RDC OpenAPI）合并为单个 monorepo 软件包
• 为专注于 RDC 的服务添加 sauce-api-mcp-rdc 入口点
• 将 RDC 服务从已弃用的 FastMCPOpenAPI 迁移到 OpenAPIProvider + FastMCP（fastmcp 3.x）
• 通过 workflow_dispatch 和 python-semantic-release 实现自动化发布工作流；由作者选择发布类型（ patch/minor/major/prerelease）
• CI 拆分为三个依次执行的阶段：集成测试（矩阵 3.10–3.12）→ 实时测试 → 慢速测试
• 使用 uv.lock 锁定依赖项，确保安装过程可重现

v1.0.3

• 更新为 Apache License 2.0（此前为 MIT）

v1.0.2

• 提交至官方 MCP Registry
• 添加 Python 3.9 支持

v1.0.1

• 全面改进 README，优化安装说明

v1.0.0

• 首次发布，完整集成 Sauce Labs API

---

为测试社区倾情打造 ❤️

许可证

Apache 2.0（1.1.0 及更高版本）

1.0.3 之前的版本采用 MIT License 发布。

免责声明

本软件按“原样”提供，不提供任何明示或默示的担保，包括但不限于适销性、特定用途适用性和不侵权的担保。在任何情况下，作者或版权持有人均不对因本软件或使用本软件或与之相关的其他交易而产生的任何索赔、损害或其他责任负责，无论该责任属于合同责任、侵权责任还是其他责任。

责任限制

在任何情况下，SAUCE LABS, INC. 均不对任何直接、间接、附带、特殊、惩罚性或后果性损害承担责任（包括但不限于采购替代商品或服务；使用、数据或利润损失；或业务中断），无论此类损害由何种原因造成，也无论基于何种责任理论（合同、严格责任或侵权责任，包括疏忽或其他原因），只要因使用本软件而以任何方式引起，即使已被告知可能发生此类损害。

一般用途

MCP 服务作为免费开源工具提供，旨在便于与公开可用的 API 交互。用户可以根据 Apache License 2.0 的条款自由修改和分发该软件。

使用本软件，即表示你承认使用风险由你自行承担，并且你有责任确保自身遵守所有适用法律法规。

赔偿

你同意赔偿并使 Sauce Labs, Inc.（“Sauce Labs”）、其高管、董事、员工和代理人免受因你访问或使用本软件而引起或以任何方式与之相关的任何及所有索赔、责任、损害、损失或费用（包括合理的律师费和成本）。

这包括但不限于：

• 你与第三方大模型提供商的交互： 你承认，本软件使用公开可用的 API 与大模型（LLM）交互。你须对使用任何第三方大模型服务承担全部责任，包括遵守大模型提供商的条款和条件，以及承担使用相关费用（例如令牌费用）。Sauce Labs 无法控制任何第三方大模型提供商的内容、隐私政策或做法，也不对此承担责任。

• 大模型生成的内容： 你须对通过使用 MCP 服务及其底层大模型而生成、接收或传输的内容承担全部责任。Sauce Labs 不认可且无法控制你或任何第三方通过该服务进行通信的内容。

• 你的代码和修改： 你基于 MCP 服务创建的任何修改、增强或衍生作品均由你自行负责；你须对其性能以及因使用这些作品而可能产生的任何责任承担全部责任。