amazon-nova-act-mcp

KO | EN

gitlite — search

#hacktoberfest #ai #typescript #go #android #deep-learning #linux #nodejs #awesome #cli #awesome-list #vue #security #ios

amazon-nova-act-mcp

(★ 11)

An MCP (Model Context Protocol) server that wraps Amazon Nova Act — AWS's browser automation agent

amazon-nova-act-mcp 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# amazon-nova-act-mcp

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
- **Agent ergonomics** — Handles complexities like automatically retrying with AgentCore browser when running into bot detection issues, and offering a unified `start_browse` entry point that triages URLs via fast HTTP fetch first and only opens a full browser session when needed.

---

## Prerequisites

- **macOS or Linux** — Windows support coming soon
- 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

The recommended way to run `amazon-nova-act-mcp` is with `uvx`, which makes the Nova Act MCP server available to your agents from whatever folder you run them. `uvx` downloads and runs the server from PyPI and doesn't require a separate installation step.

Nova Act MCP 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 amazon-nova-act-mcp --configure
```

**AWS/IAM setup (enterprise, AgentCore):**
```bash
uvx amazon-nova-act-mcp --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 amazon-nova-act-mcp --configure` to update and reconfigure.

If you prefer to install Nova Act MCP server within a virtual environment, you can install via `pip` instead. Once you have activated your virtual environment, run these commands:
```bash
pip install amazon-nova-act-mcp
amazon-nova-act-mcp --configure
```

The configuration wizard will prompt you for credentials and preferences, and write the appropriate environment variables into your MCP client config automatically. The two authentication 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 and can skip this section.

Follow the steps below if you need to manually set up Nova Act MCP server for your agent.

### 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": ["amazon-nova-act-mcp"],
      "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.

---

### Claude Code

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

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": ["amazon-nova-act-mcp"],
      "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.

---

## MCP Tools Explained

| Tool | Purpose |
|------|---------|
| `start_browse` | **Entry point for all URL access** — fast HTTP fetch first, auto-creates a browser session (local or cloud) if the page needs JavaScript or is blocked |
| `act` | Execute browser actions via natural language in an existing session |
| `act_get` | Execute + extract data with `format=text\|json` (use `schema` for structured output) |
| `go_to_url` | Navigate directly to a URL without an LLM call |
| `get_page_content` | Return current page content as `text` or `html` |
| `screenshot` | Capture screenshot to local path |
| `session_close` | Terminate a browser session and free resources |
| `session_list` | List active sessions (for debugging) |

### Verification & Direct Browser Tools

These tools support design verification workflows — checking whether a live web page matches its design specification using deterministic CSS checks. They are **opt-in** and not enabled by default.

**To enable**, add `--toolsets ui-verification` when starting the server:

```bash
amazon-nova-act-mcp --toolsets ui-verification
```

Or in your MCP client config:
```json
{
  "mcpServers": {
    "nova-act": {
      "command": "uvx",
      "args": ["amazon-nova-act-mcp", "--toolsets", "ui-verification"]
    }
  }
}
```

| Tool | Purpose |
|------|---------|
| `verify_visual_style` | Check colors, typography, spacing, radii, shadows against CSS rules |
| `verify_components` | Check component variants, props against CSS rules |
| `verify_accessibility` | Check ARIA attributes, roles, landmarks, contrast |
| `verify_project_rules` | Check token usage, conventions, layout rules |
| `verify_platform_conventions` | Check navigation patterns, page structure |
| `evaluate_js` | Run arbitrary JavaScript in the page context |
| `navigate` | Navigate to a URL via Playwright (no model call, instant) |
| `click` | Click an element by CSS selector (no model call) |
| `scroll` | Scroll the page or a container up/down (no model call) |
| `hover` | Hover over an element (no model call) |
| `press_key` | Press a keyboard key (no model call) |
| `type_text` | Type text into an input element (no model call) |

The `verify_*` tools accept rules as JSON arrays of `{name, selector, property, constraint}` and write structured results to `.ui-verification/sessions/{session_id}/{category}_assertions.json`. They support merge behavior — subsequent runs update existing results by name.

### Tool Selection Guide

| I need to... | Use this tool |
|--------------|---------------|
| Triage a URL / quick read (auto-chooses HTTP vs browser) | `start_browse(url, intent)` |
| Open a local browser session for an interactive site | `start_browse(url, intent, browser_mode="LOCAL")` |
| Open a visible local browser window for debugging | `start_browse(url, intent, browser_mode="LOCAL_HEADED")` |
| Use your system Chrome profile for a site that requires login | `start_browse(url, intent, browser_mode="LOCAL_SYSTEM_DEFAULT")` |
| Use AgentCore for a bot-protected or CAPTCHA/challenge-heavy site | `start_browse(url, intent, browser_mode="AGENTCORE")` |
| Continue interacting with a browser session | `act(session_id, prompt)` |
| Extract structured data | `act_get(session_id, prompt, format)` |
| Navigate to an exact URL in an existing session | `go_to_url(session_id, url)` |
| Get raw page text or HTML from a session | `get_page_content(session_id, format)` |
| Take a screenshot | `screenshot(session_id)` |
| Debug active sessions | `session_list()` |
| Close a session when done | `session_close(session_id)` |

---

## 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 browsers.

---

## 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 more granular control.

### Authentication

| 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. |

### Overriding Nova Act default settings

Many of the default Nova Act settings can be overridden with environment variables. For example, recording video, setting the logging folder, and setting the model version of Nova Act. Look at the [settings.py](src/amazon_nova_act_mcp/modules/settings.py) for a full list.

For local authenticated browser sessions on macOS, you can also set:

| Variable | Description |
|---|---|
| `NOVA_ACT_SYNC_CHROME_PROFILE_ON_STARTUP` | If set to `true`, syncs your Chrome profile copy into `~/.nova-act/chrome-profile` during server startup, without first running `--configure-local-browser`. |

---

amazon-nova-act-mcp

amazon-nova-act-mcp 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

amazon-nova-act-mcp

amazon-nova-act-mcp 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README