---
title: MCP
description: Learn how to use Alumnium's MCP server to enable general-purpose AI agents to automate web and mobile applications.
---

Alumnium's [Model Context Protocol][1] server enables general-purpose AI agents like Claude Code to leverage Alumnium's web and mobile automation capabilities through the standardized Model Context Protocol. This integration allows AI assistants to control browsers and mobile applications directly.

## Demo

<iframe
  width="1024"
  height="768"
  src="https://www.youtube.com/embed/DzkbOdQsloc?si=Tpo6QQYMUbML-Sab"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  referrerpolicy="strict-origin-when-cross-origin"
  allowfullscreen
/>

## Installation

The MCP Server is available in both the Python and TypeScript packages.

:::note
MCP server can be configured to use different AI providers. Follow [configuration guide][4] to learn about environment variables and setup for various AI providers. The examples below use OpenAI by default.
:::

import { Tabs, TabItem } from "@astrojs/starlight/components";

<Tabs>
<TabItem label="Python">

### Claude Code

```bash
claude mcp add alumnium --env OPENAI_API_KEY=... -- uvx alumnium mcp
```

### Codex

```bash
codex mcp add alumnium --env OPENAI_API_KEY=... -- uvx alumnium mcp
```

:::tip[Reuse your Codex subscription]
If you're already signed in to the [Codex CLI][10], you can drop `OPENAI_API_KEY` and let Alumnium reuse your ChatGPT Plus/Pro OAuth tokens instead. See the [Codex configuration][11] for details.

```bash
codex mcp add alumnium --env ALUMNIUM_MODEL=codex -- uvx alumnium mcp
```

:::

### Cursor

Add the following to `mcp.json`:

```json
{
  "mcpServers": {
    "alumnium": {
      "command": "uvx",
      "args": ["alumnium", "mcp"],
      "env": {
        "OPENAI_API_KEY": "..."
      }
    }
  }
}
```

### Gemini CLI

```bash
gemini mcp add alumnium --env OPENAI_API_KEY=... uvx alumnium mcp
```

### Visual Studio Code

```bash
code --add-mcp '{
    "name": "alumnium",
    "command": "uvx",
    "args": [
      "alumnium",
      "mcp"
    ],
    "env": {
      "OPENAI_API_KEY": "..."
    }
  }'
```

</TabItem>
<TabItem label="TypeScript">

### Claude Code

```bash
claude mcp add alumnium --env OPENAI_API_KEY=... -- npx alumnium mcp
```

### Codex

```bash
codex mcp add alumnium --env OPENAI_API_KEY=... -- npx alumnium mcp
```

:::tip[Reuse your Codex subscription]
If you're already signed in to the [Codex CLI][10], you can drop `OPENAI_API_KEY` and let Alumnium reuse your ChatGPT Plus/Pro OAuth tokens instead. See the [Codex configuration][11] for details.

```bash
codex mcp add alumnium --env ALUMNIUM_MODEL=codex -- npx alumnium mcp
```

:::

### Cursor

Add the following to `mcp.json`:

```json
{
  "mcpServers": {
    "alumnium": {
      "command": "npx",
      "args": ["alumnium", "mcp"],
      "env": {
        "OPENAI_API_KEY": "..."
      }
    }
  }
}
```

### Gemini CLI

```bash
gemini mcp add alumnium --env OPENAI_API_KEY=... npx alumnium mcp
```

### Visual Studio Code

```bash
code --add-mcp '{
    "name": "alumnium",
    "command": "npx",
    "args": [
      "alumnium",
      "mcp"
    ],
    "env": {
      "OPENAI_API_KEY": "..."
    }
  }'
```

</TabItem>
</Tabs>

## Tools

The MCP Server exposes Alumnium's core automation capabilities:

| Tool                       | Description                                                                    |
| -------------------------- | ------------------------------------------------------------------------------ |
| `start`                    | Initialize browser/mobile drivers with Appium/Selenium/Playwright capabilities |
| `stop`                     | Cleanup resources and retrieve token usage statistics                          |
| `do`                       | Execute natural language automation commands                                   |
| `check`                    | Verify statements about the current page state with optional vision support    |
| `get`                      | Extract data from pages using natural language descriptions                    |
| `wait`                     | Wait a fixed duration or until a natural language condition is met             |
| `fetch_accessibility_tree` | Debug page structure with raw accessibility tree                               |

### `start`

Initialize the browser or mobile driver session. Pass capabilities as an inline JSON string or a path to a JSON file. Supports all drivers: Appium, Selenium, or Playwright.

#### `platformName`

Selects the driver to use. Supported values are `chrome`, `ios`, and `android`. Case-insensitive.

#### `alumnium:options`

Pass `alumnium:options` in capabilities to configure Alumnium and driver behavior for the session:

```json
{
  "platformName": "chrome",
  "alumnium:options": {
    "autoswitchToNewTab": false,
    "baseUrl": "https://example.com",
    "changeAnalysis": true,
    "cookies": [
      {
        "name": "session",
        "value": "abc123",
        "domain": ".example.com"
      }
    ],
    "excludeAttributes": ["url"],
    "executablePath": "/Applications/Arc.app/Contents/MacOS/Arc",
    "headers": { "Authorization": "Bearer token" },
    "headless": true,
    "planner": false,
    "profile": "work"
  }
}
```

| Option                    | Description                                                                                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `autoswitchContexts`      | Automatically switch between native and web contexts after interactions. Appium only. Default is `true`.                                                           |
| `autoswitchToNewTab`      | Automatically switch focus to newly opened tabs. Selenium and Playwright only. Default is `true`.                                                                  |
| `baseUrl`                 | URL to navigate to when the session starts.                                                                                                                        |
| `changeAnalysis`          | Enable UI changes analysis after each `do()` call. Default is `true`.                                                                                              |
| `cookies`                 | Pre-defined cookies to set before the session starts. Selenium and Playwright only.                                                                                |
| `delay`                   | Seconds to wait after each interaction. Appium only. Default is `0`.                                                                                               |
| `excludeAttributes`       | Array of accessibility tree attributes to exclude. Reduces tree size on large pages.                                                                               |
| `executablePath`          | Path to a custom Chrome/Chromium executable (e.g. Arc, Brave). Selenium and Playwright only.                                                                       |
| `fullPageScreenshot`      | Capture full-page screenshots instead of viewport-only. Default is `false`.                                                                                        |
| `headers`                 | Custom HTTP headers for all browser requests. Selenium and Playwright only.                                                                                        |
| `headless`                | Run browser in headless mode. Selenium and Playwright only. Default is `false`.                                                                                    |
| `hideKeyboardAfterTyping` | Dismiss the on-screen keyboard after typing. Appium only. Default is `false`.                                                                                      |
| `newTabTimeout`           | Milliseconds to wait for a new tab to open after a click. Playwright only. Default is `200`.                                                                       |
| `permissions`             | Browser permissions to grant (e.g. `["geolocation"]`). Playwright only.                                                                                            |
| `planner`                 | Enable or disable the planning step in `do()`. Default is `true`.                                                                                                  |
| `profile`                 | Name of a persistent browser profile; cookies, sessions, and storage are preserved across restarts in `~/.alumnium/profiles/{name}`. Selenium and Playwright only. |
| `userAgent`               | Custom User-Agent string sent with every request. Playwright only.                                                                                                 |

#### `appium:settings`

For iOS and Android sessions, pass `appium:settings` in capabilities to configure [Appium settings][9] that are applied to the driver after it is created:

```json
{
  "platformName": "ios",
  "appium:settings": {
    "allowInvisibleElements": true,
    "ignoreUnimportantViews": true
  }
}
```

### `stop`

Stops running driver session and cleans up resources. Returns path to the artifacts directory, token usage statistics for the session and optionally saves the execution [cache][5].

### `do`

Perform [actions][6] in the application using natural language commands and return summary of the performed steps. Alumnium automatically captures screenshot upon completion and stores it in the artifacts directory.

### `check`

[Verify][7] application state and run assertions using natural language commands. Returns the result of the check along with explanation the verification was evaluated. Alumnium automatically captures screenshot upon completion and stores it in the artifacts directory.

### `get`

[Extract][8] data from the application based on natural language descriptions. If data is not found, returns explanation why it can't be retrieved. Alumnium automatically captures screenshot upon completion and stores it in the artifacts directory.

### `wait`

Wait for a fixed duration or until a natural language condition is met. Pass a number (1–30) to wait that many seconds, or a string condition (e.g. `"user is logged in"`) to poll with AI-powered verification until it becomes true or a timeout is reached.

### `fetch_accessibility_tree`

Returns the raw accessibility tree of the current page as XML. Useful for debugging when `do`, `check`, or `get` behave unexpectedly — inspect the tree to verify element visibility, roles, and attributes.

[1]: https://modelcontextprotocol.io
[2]: https://docs.astral.sh/uv/
[3]: https://docs.astral.sh/uv/getting-started/installation/
[4]: /docs/getting-started/configuration
[5]: /docs/guides/caching
[6]: /docs/guides/actions
[7]: /docs/guides/verifications
[8]: /docs/guides/retrievals
[9]: https://appium.io/docs/en/2.0/guides/settings/
[10]: https://github.com/openai/codex
[11]: /docs/getting-started/configuration#codex
