Metadata-Version: 2.4
Name: amazon-nova-act-mcp
Version: 1.0.60.0
Summary: Stateful MCP server for Nova Act prompt iteration workflows
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.11
Requires-Dist: boto3<2.0.0,>=1.35.0
Requires-Dist: cryptography<46.0,>=42.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: mcp[cli]<2.0.0,>=1.12.0
Requires-Dist: nova-act>=3.3.35.0
Requires-Dist: numpy<2.3,>=1.26
Requires-Dist: pandas<2.3,>=2.0
Requires-Dist: pillow<12.0,>=10.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Description-Content-Type: text/markdown

# nova-act-mcp-server

An MCP (Model Context Protocol) server that wraps [Amazon Nova Act](https://aws.amazon.com/nova/act/) — AWS's browser automation agent. It enables AI assistants like Claude to control a browser through natural language while maintaining persistent browser sessions across multiple tool calls.

---

## Features

- **Natural language browser automation** — control a browser using plain English to extract structured data, fill forms, run UI tests, and much more
- **Parallel browser sessions** — run multiple independent browser sessions simultaneously; each session gets its own isolated runtime so they never interfere with each other
- **Bot detection handling** — built-in support for [Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/), the emerging IETF standard for legitimate bot identification
- **Flexible authentication** — use a `NOVA_ACT_API_KEY` for quick setup, or AWS IAM credentials for enterprise and production deployments

---

## Prerequisites

- Python 3.10+
- [`uv`](https://docs.astral.sh/uv/) — install it with `curl -LsSf https://astral.sh/uv/install.sh | sh`
- An AWS account with Nova Act access, **or** a `NOVA_ACT_API_KEY`

---

## Installation & configuration

[//]: # (pragma: internal-start)
### Install with AIM (Recommended)

```bash
aim mcp install nova-act-mcp && nova-act-mcp-server --configure
```

This installs the server and registers it with AIM-compatible clients (Kiro, Claude Code, etc.).
[//]: # (pragma: internal-stop)

The recommended way to run `nova-act-mcp-server` is with `uvx`, which runs it directly from PyPI without a separate install step. The server has three setup commands:

| Command | Purpose |
|---|---|
| `--configure` | Quick setup: API key + MCP client config |
| `--configure-aws` | Advanced setup: AWS/IAM auth, AgentCore cloud browsers, and MCP client config |
| `--configure-local-browser` | Sync your Chrome profile for authenticated browser sessions (macOS) |

**Quick start (API key):**
```bash
uvx nova-act-mcp-server --configure
```

**AWS/IAM setup (enterprise, AgentCore):**
```bash
uvx nova-act-mcp-server --configure-aws
```

> **Note:** `uvx` caches packages locally and won't automatically pick up new versions. To always run the latest, add `--refresh` to your args in the MCP client config (see next section), or run `uvx --refresh nova-act-mcp-server --configure` to update and reconfigure.

If you prefer to install via `pip` instead:
```bash
pip install nova-act-mcp-server
nova-act-mcp-server --configure
```

Each wizard will prompt you for credentials and preferences, then write the appropriate environment variables into your MCP client config automatically. The two auth wizards are additive — you can run `--configure` first for API key access, then `--configure-aws` later to add AgentCore support.

---

## Connecting to an agent

When you run `--configure` or `--configure-aws`, you have the option of configuring the MCP server for Claude or Kiro. If you have already done that, then you are all set.

Follow the steps below if you need to set it up manually.

### Claude Code

Add the server using the Claude Code CLI:
```bash
claude mcp add nova-act-mcp --scope user -- nova-act-mcp-server
```

Or add it manually to `~/.claude.json` (user scope, all projects) or `.mcp.json` (project scope, shared with your team):
```json
{
  "mcpServers": {
    "nova-act-mcp": {
      "command": "uvx",
      "args": ["nova-act-mcp-server"],
      "env": {
        "NOVA_ACT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Verify it's connected by running `claude mcp list`, or typing `/mcp` inside a Claude Code session.

---

### Kiro

**Via the Kiro IDE UI:** Navigate to **Kiro → MCP Servers**, click **+ Add**, and paste the config below.

**Via config file:** Edit `~/.kiro/settings/mcp.json` for global use, or `.kiro/settings/mcp.json` for project-specific use.
```json
{
  "mcpServers": {
    "nova-act-mcp": {
      "command": "uvx",
      "args": ["nova-act-mcp-server"],
      "env": {
        "NOVA_ACT_API_KEY": "${NOVA_ACT_API_KEY}"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

> **Tip:** Use `${VARIABLE_NAME}` syntax to reference environment variables rather than hardcoding credentials. Never commit config files containing secrets to version control.

---

## MCP Tools Explained

| Tool | Purpose |
|------|---------|
| `probe_url` | **Triage a URL** - fetch via HTTP, detect blockers, return content or recommend session |
| `session_create` | Start a **local** browser session |
| `session_create_agentcore` | Start a **cloud** browser session via Bedrock AgentCore (anti-bot bypass) |
| `session_close` | Terminate browser and cleanup |
| `session_list` | List active sessions (for debugging) |
| `act` | Execute browser actions via natural language |
| `act_get` | Execute + extract with `format=text|json` |
| `go_to_url` | Navigate directly to URL without LLM call |
| `get_page_content` | Return current page content as `text` or `html` |
| `screenshot` | Capture screenshot to local path or optional S3 URL |

### Tool Selection Guide

| I need to... | Use this tool |
|--------------|---------------|
| Triage a URL / quick read | `probe_url(url, intent)` |
| Interactive workflow (local) | `session_create` + `act` |
| Anti-bot bypass (cloud) | `session_create_agentcore` + `act` |
| Navigate to exact URL | `go_to_url(session_id, url)` |
| Extract structured data | `act_get(session_id, prompt, format)` |
| Get raw HTML from session | `get_page_content(session_id)` |
| Take screenshot | `screenshot(session_id)` |
| Debug active sessions | `session_list()` |

---

## Authentication

The server supports two authentication modes. An explicit API key takes priority; IAM/AWS credentials are used as the fallback.

**Option A — API key (simplest):**

Run `--configure` to set up API key auth. You can get an API key at [nova.amazon.com/act](nova.amazon.com/act).

**Option B — IAM / AWS credentials:**

Run `--configure-aws` to set up AWS/IAM auth, validate your credentials, and optionally configure AgentCore cloud browsers.

Both modes can coexist — if an API key is present it takes priority for Nova Act, while AWS credentials are always used for AgentCore.

---

## Environment variables

All behaviour can be tuned via environment variables. The `--configure` and `--configure-aws` wizards handle the most common ones, but the full set is documented below for advanced use.

### Auth

| Variable | Description |
|---|---|
| `NOVA_ACT_API_KEY` | API key auth. Takes priority over IAM when set. |
| `AWS_PROFILE` | AWS profile to use for IAM auth. |
| `AWS_REGION` | AWS region for IAM auth and AWS clients. |
| `AWS_DEFAULT_REGION` | Fallback region if `AWS_REGION` is not set. |

### Nova Act session defaults

| Variable | Description |
|---|---|
| `NOVA_ACT_MODEL_ID` | Model override. Defaults to `nova-act-latest`. |
| `NOVA_ACT_WORKFLOW_DEFINITION_NAME` | Overrides the default workflow definition name (IAM mode). |
| `NOVA_ACT_S3_EXPORT_BUCKET` | S3 bucket for workflow definition exports (logs, videos). Set via `--configure-aws`. |
| `NOVA_ACT_LOGS_DIRECTORY` | Directory for session logs. |
| `NOVA_ACT_RECORD_VIDEO` | Set to `true` to record video of browser sessions. |

### AgentCore browser

| Variable | Description |
|---|---|
| `NOVA_ACT_PREFER_AGENTCORE` | Set to `true` to disable local browser sessions and instead use AgentCore Browser tool sessions. |
| `NOVA_ACT_AGENTCORE_EXECUTION_ROLE_ARN` | Default IAM execution role ARN for AgentCore Browser tool sessions. |
| `NOVA_ACT_AGENTCORE_REGION` | AgentCore region override. |
| `NOVA_ACT_AGENTCORE_BROWSER_NAME` | Default AgentCore browser name. |
| `NOVA_ACT_AGENTCORE_BROWSER_ID` | Use an existing AgentCore browser definition directly. |
| `NOVA_ACT_AGENTCORE_NETWORK_MODE` | AgentCore network mode. |
| `NOVA_ACT_AGENTCORE_SESSION_TIMEOUT_SECONDS` | AgentCore session timeout in seconds. |

---

## Architecture
```
Claude/LLM  <--stdio JSON-RPC-->  MCP Server  <---->  Nova Act  <---->  Browser
                                      |
                                      v
                                SessionManager (keeps browsers alive)
```

Key design decisions:

- **Stateful sessions** — Browser sessions are expensive to create, so the server keeps them alive with a 30-minute idle TTL.
- **Async lock per session** — Prevents concurrent actions on the same browser.
- **Agent ergonomics** — Handles complexities like automatically retrying with AgentCore browser when running into bot detection issues, and offering a `probe_url` tool for cases where the agent just needs simple access to a website without any complex interactions, such as checking weather or getting a stock price.
- **Dual auth support** — IAM/AWS is the default; an explicit `NOVA_ACT_API_KEY` takes priority when set.

---