# MCP Setup

Use this guide to connect FinalRun MCP with supported clients on macOS and Windows.

## Supported clients

* Claude Code
* Claude Desktop
* Cursor
* Codex
* Antigravity
* And other AI IDEs if it's supported by npx skills

## Prerequisites

* macOS or Windows
* Node.js and npm installed
* A FinalRun API key
* FinalRun MCP installed locally

## 1. Install Agent Skills

Run the following command to install FinalRun agent skills:

```bash
npx skills add https://github.com/final-run/agent-skills.git
```

This installs the FinalRun agent skills that extend your AI client's capabilities for mobile testing.

## 2. Install FinalRun MCP

{% tabs %}
{% tab title="macOS" %}
Run:

```bash
curl -fsSL https://get-mcp.finalrun.app/install.sh | bash
```

After installation, the MCP cli should be available at:

```bash
~/.finalrun/bin/finalrun-mcp-cli
```

{% endtab %}

{% tab title="Windows" %}
Open PowerShell and run:

```powershell
irm https://finalrun-mcp-exec.s3.pl-waw.scw.cloud/install.ps1 | iex
```

After installation, the MCP cli should be available at:

```
C:/Users/<username>/.finalrun/bin/finalrun-mcp-cli.ps1
```

{% endtab %}
{% endtabs %}

## 3. Get your FinalRun API key

You can generate or copy your API key from either location:

* FinalRun macOS app -> `Profile` -> `API Key`
* OR [FinalRun Studio](https://studio.finalrun.app) -> `Profile` -> `API Key`

## 4. Configure your client

### Claude CLI

{% tabs %}
{% tab title="macOS" %}
Run:

```bash
claude mcp add --transport stdio finalrun -- ~/.finalrun/bin/finalrun-mcp-cli --api-key YOUR_API_KEY
```

{% endtab %}

{% tab title="Windows" %}
Run:

```powershell
claude mcp add --transport stdio finalrun -- powershell -File C:/Users/<username>/.finalrun/bin/finalrun-mcp-cli.ps1 --api-key YOUR_API_KEY
```

{% endtab %}
{% endtabs %}

### Claude Desktop

{% tabs %}
{% tab title="macOS" %}
Add this server config in Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "finalrun": {
      "command": "~/.finalrun/bin/finalrun-mcp-cli",
      "args": ["--api-key", "YOUR_API_KEY"]
    }
  }
}
```

{% endtab %}

{% tab title="Windows" %}
Add this server config in Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "finalrun": {
      "command": "powershell",
      "args": ["-File", "C:/Users/<username>/.finalrun/bin/finalrun-mcp-cli.ps1", "--api-key", "YOUR_API_KEY"]
    }
  }
}
```

> Replace `<username>` with your Windows username.
> {% endtab %}
> {% endtabs %}

### Cursor

{% tabs %}
{% tab title="macOS" %}
Add this server config in Cursor MCP configuration:

```json
{
  "mcpServers": {
    "finalrun": {
      "command": "~/.finalrun/bin/finalrun-mcp-cli",
      "args": ["--api-key", "YOUR_API_KEY"]
    }
  }
}
```

{% endtab %}

{% tab title="Windows" %}
Add this server config in Cursor MCP configuration:

```json
{
  "mcpServers": {
    "finalrun": {
      "command": "powershell",
      "args": ["-File", "C:/Users/<username>/.finalrun/bin/finalrun-mcp-cli.ps1", "--api-key", "YOUR_API_KEY"]
    }
  }
}
```

> Replace `<username>` with your Windows username. Use forward slashes (`/`) in the path.
> {% endtab %}
> {% endtabs %}

### Codex

{% tabs %}
{% tab title="macOS" %}
Add this server config in your Codex TOML configuration:

```toml
[mcp_servers.finalrun]
command = "~/.finalrun/bin/finalrun-mcp-cli"
args = ["--api-key", "YOUR_API_KEY"]
```

{% endtab %}

{% tab title="Windows" %}
Add this server config in your Codex TOML configuration:

```toml
[mcp_servers.finalrun]
command = "powershell"
args = ["-File", "C:/Users/<username>/.finalrun/bin/finalrun-mcp-cli.ps1", "--api-key", "YOUR_API_KEY"]
```

> Replace `<username>` with your Windows username.
> {% endtab %}
> {% endtabs %}

## 5. Verify setup

1. Restart your AI client after config changes.
2. Just ask claude or cursor to ping for `finalrun` in order to verify if it's connected.
3. Run a simple test prompt in the client to confirm FinalRun tools are available.

## Troubleshooting

{% tabs %}
{% tab title="macOS" %}

* Ensure `~/.finalrun/bin/finalrun-mcp-cli` exists and is executable.
* Ensure your API key is valid.
  {% endtab %}

{% tab title="Windows" %}

* Ensure `C:\Users\<username>\.finalrun\bin\finalrun-mcp-cli.ps1` exists.
* Ensure your API key is valid.
* If scripts are blocked, run `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned` in PowerShell. I faced a similar issue, I asked [chatgpt](https://chatgpt.com/share/69a66e2b-3654-8010-885e-b64942e1c807)
* Ensure `C:\Users\<username>\.finalrun\bin` is on your PATH. You may need to restart your terminal after installation.
  {% endtab %}
  {% endtabs %}