Kobiton Automate

Claude Code plugin for the Kobiton mobile testing platform. Manage devices, upload apps, run automation sessions, and view test results directly from your AI coding assistant.

Before You Begin

Make sure you have:

A Kobiton account — sign up at kobiton.com if you don't have one
Claude Code installed and working — verify by running claude in your terminal (install guide)
A workspace folder opened — Claude Code must be launched from a project directory (e.g. cd my-project && claude)

Installation

From Claude Code Marketplace

# add kobiton marketplace
/plugin marketplace add kobiton/automate

# then install the automate plugin
/plugin install automate@kobiton

Login

In Claude Code, type /mcp to open the MCP server list
Select the kobiton server — a browser window will open for Kobiton login
Sign in with your Kobiton credentials. Tokens are managed automatically.

The .mcp.json points to the Kobiton MCP server. Authentication is handled via OAuth 2.1 — when you connect to the server through /mcp, Claude Code opens a browser for login.

{
  "mcpServers": {
    "kobiton": {
      "type": "http",
      "url": "https://api.kobiton.com/mcp"
    }
  }
}

After installation and authentication, verify the plugin loaded by asking Claude: "List my Kobiton devices". If tools aren't recognized, see Troubleshooting.

API Key Authentication (Alternative)

For CI/CD pipelines or headless environments that cannot open a browser, use API key auth instead:

Copy .mcp.apikey-example.json to .mcp.json
Generate an API key at Kobiton Portal > Settings > API Keys
Set the environment variable:

# Add to ~/.zshrc, ~/.bashrc, or ~/.bash_profile
export KOBITON_AUTH="Basic $(echo -n 'username:apikey' | base64)"

Reload your shell and restart Claude Code.

Note: OAuth and API key auth cannot coexist in a single .mcp.json. The default config (no headers block) uses OAuth via browser login. The API key config uses a headers block with ${KOBITON_AUTH}. To switch, replace .mcp.json with the appropriate format.

Install in Other MCP Clients

The Kobiton MCP server (https://api.kobiton.com/mcp) speaks the open Model Context Protocol and can be consumed by any spec-compliant MCP client — not just Claude Code. Below are the install configs for several common clients. All configs below are derived from each client's published documentation; the Kobiton-side OAuth flow is the same across all of them, but Intent Solutions has not yet end-to-end-tested every client. Please file issues if a config below does not work for your setup.

Cursor

Cursor reads MCP servers from .cursor/mcp.json at the project root (or ~/.cursor/mcp.json for global). This repo ships a default project-level config at .cursor/mcp.json:

{
  "mcpServers": {
    "kobiton": {
      "url": "https://api.kobiton.com/mcp"
    }
  }
}

On first connection Cursor opens a browser for OAuth login (same flow as Claude Code's /mcp command). Cursor's fixed OAuth redirect URL is cursor://anysphere.cursor-mcp/oauth/callback. Reference: cursor.com/docs/context/mcp.

Gemini CLI

Gemini CLI reads extension configs from gemini-extension.json at the repo root. This repo ships one via upstream PR #28 (Phase 1 — Gemini CLI support by @huytunguyenn). Install via:

gemini extensions install kobiton/automate

Cross-tool agent instructions live in AGENTS.md, which Gemini CLI consumes as contextFileName.

Codex CLI

Codex CLI reads MCP server configs from ~/.codex/config.toml. Add:

[mcp_servers.kobiton]
url = "https://api.kobiton.com/mcp"

Codex CLI consumes AGENTS.md for cross-tool agent instructions. Reference: openai.com/codex (Codex CLI docs).

GitHub Copilot CLI

GitHub Copilot CLI support was added in upstream PR #10. See PR body for install instructions specific to your Copilot CLI version.

ChatGPT Apps SDK

ChatGPT (via the Apps SDK) consumes MCP servers via HTTPS endpoint registered in ChatGPT developer mode. Point ChatGPT at:

https://api.kobiton.com/mcp

The Apps SDK does not require a separate manifest file; tool descriptors, OAuth flow, and _meta.ui widget hints flow through the MCP protocol itself. Reference: developers.openai.com/apps-sdk/build/mcp-server.

Continue (and other generic MCP clients)

Most generic MCP clients (Continue, Cline, etc.) support the open Streamable HTTP transport. Use a config block like:

{
  "mcpServers": {
    "kobiton": {
      "url": "https://api.kobiton.com/mcp"
    }
  }
}

Adjust to your client's specific format. The server URL is the same; OAuth handshake is the same. If your client doesn't support OAuth, fall back to the API-key auth path (see API Key Authentication above) — most clients accept custom headers blocks.

Capability matrix (what works where)

Client	OAuth login	API key auth	AGENTS.md / skill	Hooks (Claude-Code-specific)
Claude Code	✅	✅	✅ skill	✅
Cursor	✅	via custom `headers` block	n/a (uses Cursor rules)	❌
Gemini CLI	✅	via env var	✅ AGENTS.md	❌
Codex CLI	✅	via env var	✅ AGENTS.md	❌
GitHub Copilot CLI	✅	via env var	✅ AGENTS.md	❌
ChatGPT Apps SDK	✅	n/a (web app)	n/a (uses tool descriptors)	❌
Continue / Cline	✅	✅	n/a	❌

Hooks (the hooks/ directory) are a Claude Code-specific feature; other MCP clients won't honor them. Server-side observability via OpenTelemetry (proposed in Intent Solutions fork issue jeremylongshore/automate#28) would be the cross-client equivalent — works uniformly for every client because instrumentation lives at the MCP server, not the agent host.

What You Can Do

Ask Claude naturally:

"List my available Android devices"
"Upload my-app.apk and run tests on the Pixel 6"
"Show me the results for session 502"
"Run my Appium test script on the Pixel 6"

Tools (12)

Devices

Tool	Description
`listDevices`	List available devices filtered by platform, availability, or group
`getDeviceStatus`	Get real-time status of a specific device
`reserveDevice`	Reserve a device for exclusive testing
`terminateReservation`	Release a reserved device by terminating its reservation

Sessions

Tool	Description
`listSessions`	List test sessions with filters for status, device, platform
`getSession`	Get session details including commands, capabilities, metadata
`getSessionArtifacts`	Get download URLs for video, logs, screenshots, reports
`terminateSession`	Stop a running test session

Apps

Tool	Description
`listApps`	List uploaded app builds in your organization
`uploadAppToStore`	Upload an app to Kobiton Store (permanent, visible in portal)
`confirmAppUpload`	Confirm uploaded app for tracking record
`getApp`	Get app details and version history

Skills

run-automation-suite -- Guided workflow that walks you through app upload, device selection, local Appium script execution (Node.js, Python, .NET, Java), and result collection.

Agents (3)

Specialized subagents that encapsulate parts of the run-automation-suite workflow. Claude Code reads agent definitions from agents/ and may delegate specific decisions to them. Other MCP clients don't consume agent definitions today.

Agent	Role
`appium-capability-reconciler`	Owns Step 3 of `run-automation-suite`. Parses test scripts (Node/Python/.NET/Java), applies the three-policy reconciliation per `references/capabilities.md`.
`kobiton-session-triage`	Fires after non-success terminal state (`FAILED` / `TIMEOUT` / `ERROR`). Pulls `getSessionArtifacts`, matches the failure against the documented R2 audit catalog of known platform failure modes, surfaces structured root cause + recommended fix.
`device-picker`	Owns Step 2. Translates fuzzy natural-language device requests (e.g. "a Pixel 7 if available, otherwise any Android 13+") into a concrete `listDevices` filter + ranked candidates; confirms with the user before reserving.

Hooks (Claude Code-specific)

This plugin ships hooks/hooks.json with four advisory-only handlers that fire PreToolUse and PostToolUse around the Kobiton MCP tool calls. All handlers are pure — no authenticated API calls from the hooks themselves.

Handler	Event	Matcher	What it does
`validate-userintent`	PreToolUse	every Kobiton tool	Validates the `userIntent` argument matches the documented format; denies the call if malformed.
`advise-pre-terminate-cooldown`	PreToolUse	`terminateSession`	Allows the call but injects a notice that the device enters ~5min cleanup cooldown post-termination.
`advise-app-upload-poll`	PostToolUse	`confirmAppUpload`	Injects an advisory recommending the agent poll `getApp(appId)` until the async parser finishes.
`advise-post-terminate-cooldown`	PostToolUse	`terminateSession`	Confirms the cooldown window post-termination with `sessionId` for traceability.

Full design + threat model: hooks/README.md and hooks/THREAT-MODEL.md. Other MCP clients have no equivalent hook system; for cross-client observability the right substrate is server-side OpenTelemetry instrumentation (see jeremylongshore/automate#28).

Running Automation Tests

Use the run-automation-suite skill to run local Appium test scripts. Claude reads your script, extracts capabilities, confirms the target device, and executes the script locally. Supports Node.js (.js), Python (.py), .NET (.cs), and Java (.java) scripts.

Troubleshooting

Updating the Plugin

After the plugin is updated upstream, pull the latest version:

/plugin install automate@kobiton

To make sure Claude picks up the changes with no stale cache:

Run /reload-plugins to reload all plugins in the current session
If tools still behave unexpectedly, run /clear to reset the session context
As a last resort, quit Claude Code and start a new session

Common Issues

Plugin features not working or behaving unexpectedly

Some older versions of Claude Code don't support the plugin features this plugin relies on. Make sure you're on the latest version:

npm install -g @anthropic-ai/claude-code@latest

Then restart Claude Code and try again.

"It keeps asking me to open a folder"

Claude Code requires a working directory. Launch it from inside a project folder:

cd my-project
claude

If you see this prompt repeatedly, make sure you are not running claude from your home directory or root (/).

"Plugin not found in marketplace"

The Kobiton marketplace must be added before installing:

/plugin marketplace add kobiton/automate
/plugin install automate@kobiton

If it still isn't found, check your internet connection and ensure you're running the latest version of Claude Code (claude update).

"claude: command not found"

Claude Code is not installed or not in your PATH.

Install: follow the official install guide
PATH issue: if you installed via npm, make sure your npm global bin directory is in your PATH:
```
npm install -g @anthropic-ai/claude-code
```
Then open a new terminal window and try claude again.

"Nothing happens after install"

The plugin installed but tools don't appear or Claude doesn't recognize Kobiton commands.

Run /reload-plugins to force Claude to pick up the new plugin
Try asking: "List my Kobiton devices"
If still not working, quit Claude Code entirely and start a fresh session
Verify .mcp.json exists in the plugin directory — it tells Claude where the Kobiton MCP server lives

"Device not found"

The device may be offline, reserved by another user, or no longer in your device list. Use listDevices with available: true to find currently online devices.

"Upload timeout"

Large app files or slow connections can cause uploads to time out. Retry the upload — pre-signed URLs expire after 30 minutes, so a new URL will be generated automatically.

Still Stuck?

For additional help, open an issue at github.com/kobiton/automate/issues or ask in #general-discussion on Discord. Feel free to share feature requests. We welcome product feedback and will consider it as we continue to improve the platform.

Privacy & Data

This plugin connects to the Kobiton cloud API (api.kobiton.com) over HTTPS (TLS 1.2+).

Authentication:

OAuth 2.1 (default): Claude Code opens a browser for Kobiton login. Short-lived access tokens are stored securely in the system keychain by Claude Code. No credentials are stored in the project.
API Key (alternative): The KOBITON_AUTH environment variable is sent via the Authorization header on each request. The value is stored only in your shell profile, never committed to the repo.

Data handling:

The plugin does not store any data locally beyond what Claude Code retains in its conversation context.
Tool responses (device lists, session details, test results) pass through Claude Code's context window and are subject to Anthropic's Privacy Policy.
App binaries uploaded via uploadAppToStore are sent directly to Kobiton's pre-signed S3 URLs, not through Claude Code.

For details on how Kobiton handles your data, see the Kobiton Privacy Policy and Trust Center.

Development

The tools/ directory contains reference YAML schemas that mirror the MCP server's tool definitions. They are published to S3 for the backend but are not consumed by the plugin at runtime.

# Install dependencies
pnpm install

# Validate manifests and schemas
pnpm run validate

# Run tests
pnpm test

# Build combined tool definitions (for S3 publishing)
pnpm run build

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.claude-plugin		.claude-plugin
.cursor		.cursor
.github		.github
agents		agents
assets		assets
docs		docs
hooks		hooks
scripts		scripts
skills/run-automation-suite		skills/run-automation-suite
tools		tools
.gitignore		.gitignore
.mcp.apikey-example.json		.mcp.apikey-example.json
.mcp.dev-local.json		.mcp.dev-local.json
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml

Folders and files

Latest commit

History

Repository files navigation

Kobiton Automate

Before You Begin

Installation

From Claude Code Marketplace

Login

API Key Authentication (Alternative)

Install in Other MCP Clients

Cursor

Gemini CLI

Codex CLI

GitHub Copilot CLI

ChatGPT Apps SDK

Continue (and other generic MCP clients)

Capability matrix (what works where)

What You Can Do

Tools (12)

Devices

Sessions

Apps

Skills

Agents (3)

Hooks (Claude Code-specific)

Running Automation Tests

Troubleshooting

Updating the Plugin

Common Issues

Still Stuck?

Privacy & Data

Development

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages