Sauce Labs MCP Server

A Model Context Protocol (MCP) server that provides comprehensive integration with the Sauce Labs testing platform. This package includes two complementary MCP servers enabling AI assistants to interact with Sauce Labs' device cloud, manage test jobs, analyze builds, and monitor testing infrastructure through natural language conversations.

Servers

This package provides two separate MCP servers optimized for different use cases:

sauce-api-mcp (Core Server) — Full Sauce Labs API integration for account management, device discovery, job analysis, builds, storage, and tunnels.

sauce-api-mcp-rdc (RDC Server) — Real Device Cloud (RDC) focused server. Dynamically generates MCP tools at startup from the official Sauce Labs OpenAPI spec using FastMCP with an OpenAPIProvider, so the tool set is always up-to-date without code changes. Includes a small set of handwritten tools for endpoints that need special handling (binary payloads, session lifecycle, app installation polling).

Both servers can be configured simultaneously in your LLM client for full Sauce Labs coverage.

Features

🚀 Core Capabilities

• Account Management: View account details, team information, and user permissions
• Device Cloud Access: Browse 300+ real devices (iOS, Android) and virtual machines
• Test Job Management: Retrieve recent jobs, analyze test results, and debug failures
• Build Monitoring: Track build status, view job collections, and analyze test suites
• Storage Management: Manage uploaded apps and test artifacts
• Tunnel Monitoring: Check Sauce Connect tunnel status and configuration

🔧 Advanced Features

• Real-time Device Status: Monitor device availability and usage across data centres
• Cross-platform Testing: Support for both Virtual Device Cloud (VDC) and Real Device Cloud (RDC)
• Test Analytics: Detailed job information including logs, videos, and performance metrics
• Team Collaboration: Multi-team support with proper access controls
• Dynamic RDC API: sauce-api-mcp-rdc auto-discovers the latest RDC v2 endpoints from the OpenAPI spec at startup; the cached spec is used as a fallback when the network is unavailable
• Response shaping: Large API list responses are automatically truncated to keep LLM context budget under control ( configurable via SAUCE_MCP_MAX_RESPONSE_ITEMS)
• File safety: File push/pull operations on devices are restricted to ~/.sauce-mcp/files/ to prevent path traversal

Prerequisites

• Python 3.10+
• pip
• Sauce Labs account with API access
• Claude Desktop, Gemini CLI, Goose, or another MCP-compatible LLM client

Installation

Install the package from PyPI:

pip install sauce-api-mcp

This installs both servers and registers their command-line entry points:

• sauce-api-mcp — core server
• sauce-api-mcp-rdc — RDC OpenAPI server

Verify installation:

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

Configuration for LLM Clients

Claude Desktop (Mac / Linux / Windows)

1. Locate your Claude Desktop config file:

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

2. Find your Python installation's bin directory:

   server.ts

   Copy

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

3. Add both servers to your config:

   config.json

   Copy

   {
     "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. Restart Claude Desktop to load the servers.

Gemini CLI

Add to ~/.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

Add to ~/.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

Environment Variables (Alternative)

Instead of adding credentials to config files, you can export them as environment variables:

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

Then omit the env block from your config. Both servers will automatically pick them up.

Configuration

Required Environment Variables

Optional Environment Variables

Getting Your Sauce Labs Credentials

1. Log into your Sauce Labs account
2. Navigate to Account → User Settings
3. Copy your Username and Access Key

Troubleshooting Installation

"Command not found: sauce-api-mcp"

The entry point script isn't in your PATH. Use the full path approach:

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

"ENOENT: no such file or directory" in MCP client

The MCP client is using a different Python environment. Solutions:

1. Use the full absolute path (recommended) — update your config with the path printed by python3 -c "import sys; print(sys.prefix + '/bin/sauce-api-mcp')", not just which sauce-api-mcp
2. Module invocation (fallback):
   json

   Copy

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

Example Prompts

• "Show me my recent test failures"
• "Find available iPhone 16 devices"
• "Analyse the performance of my latest build"
• "Open a session on a Samsung device and install my app"
• "What tunnels do I have running right now?"

Available Tools

Core Server (sauce-api-mcp)

Account & Organisation

Device Management

Test Jobs

Builds

Storage

Tunnels

Test Assets & Logs

RDC Server (sauce-api-mcp-rdc)

The RDC server auto-generates tools from the Sauce Labs RDC v2 OpenAPI spec. The full tool list varies as the spec evolves, but the categories below are always present.

Session Management

Device Discovery

App Management

Device Interaction

File Operations

Network & Proxy

Appium

Development Setup

Prerequisites

• Python 3.10+
• uv package manager
• Git

Clone and Setup

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

This creates a virtual environment and installs all dependencies (including test extras) in editable mode.

Project Structure

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

Running the Servers Locally

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

Both will print Error: This server is not meant to be run interactively — this is expected (they communicate over stdio with MCP clients, not the terminal).

To point your MCP client at a local development checkout:

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

Running Tests

Tests are split into three groups:

# 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

Adding Dependencies

uv add httpx
uv add --dev pytest-asyncio

CI / Release Workflow

Continuous Integration

Every pull request targeting main runs three sequential jobs via build.yml:

1. test — integration tests across Python 3.10, 3.11, 3.12 (in parallel)
2. test-live — live tests on Python 3.12 (after test)
3. test-slow — slow tests on Python 3.12 (after test-live)

Releases

Releases are triggered manually via the Release workflow (publish.yml) in GitHub Actions:

1. Go to Actions → Release → Run workflow
2. Choose the release type: patch, minor, major, or prerelease
3. For pre-releases, optionally set the token (alpha, beta, rc)

The workflow then:

• Bumps the version in pyproject.toml and server.json using python-semantic-release
• Creates a v* git tag and a GitHub Release with auto-generated changelog
• Publishes stable releases to PyPI and the MCP Registry
• Publishes pre-releases (alpha/beta/rc) to TestPyPI only

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Getting Help

• Sauce Labs Documentation: docs.saucelabs.com
• API Reference: docs.saucelabs.com/dev/api
• Support: Contact Sauce Labs support through your account dashboard
• GitHub Issues: Report bugs or request features

Changelog

For a full history of releases and changes, see the GitHub Releases page.

v1.1.0

• Merged sauce-api-mcp and sauce-labs-mcp (RDC OpenAPI) into single monorepo package
• Added sauce-api-mcp-rdc entry point for the RDC-focused server
• Migrated RDC server from deprecated FastMCPOpenAPI to OpenAPIProvider + FastMCP (fastmcp 3.x)
• Automated release workflow via workflow_dispatch with python-semantic-release; release type chosen by the author ( patch/minor/major/prerelease)
• CI split into three sequential stages: integration tests (matrix 3.10–3.12) → live tests → slow tests
• Locked dependencies with uv.lock for reproducible installs

v1.0.3

• Updated to Apache License 2.0 (previously MIT)

v1.0.2

• Submitted to official MCP Registry
• Added Python 3.9 support

v1.0.1

• Overhauled README with improved install instructions

v1.0.0

• Initial release with full Sauce Labs API integration

Made with ❤️ for the testing community

License

Apache 2.0 (versions 1.1.0+)

Versions prior to 1.0.3 were released under the MIT License.

Disclaimer of Warranties

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Limitation of Liability

IN NO EVENT SHALL SAUCE LABS, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT ( INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

General Use

The MCP Server is provided as a free and open-source tool to facilitate interaction with publicly available APIs. Users are free to modify and distribute the software under the terms of the Apache License 2.0.

By using this software, you acknowledge that you are doing so at your own risk and that you are responsible for your own compliance with all applicable laws and regulations.

Indemnification

You agree to indemnify and hold harmless Sauce Labs, Inc. ("Sauce Labs"), its officers, directors, employees, and agents from and against any and all claims, liabilities, damages, losses, or expenses, including reasonable attorneys' fees and costs, arising out of or in any way connected with your access to or use of this software.

This includes, but is not limited to:

• Your Interaction with Third-Party LLM Providers: You acknowledge that this software utilises publicly available APIs for interaction with a Large Language Model (LLM). You are solely responsible for your use of any third-party LLM services, including your adherence to the terms and conditions of the LLM provider and any costs associated with your use, such as token fees. Sauce Labs has no control over, and assumes no responsibility for, the content, privacy policies, or practices of any third-party LLM providers.

• Content Generated by the LLM: You are solely responsible for the content generated, received, or transmitted through your use of the MCP Server and the underlying LLM. Sauce Labs does not endorse and has no control over the content of communications made by you or any third party through the server.

• Your Code and Modifications: Any modifications, enhancements, or derivative works you create based on the MCP Server are your own, and you are solely responsible for their performance and any liabilities that may arise from their use.