amazon-nova-act-mcp 1.0.101.0

Stateful MCP server for Nova Act prompt iteration workflows

amazon-nova-act-mcp

An MCP (Model Context Protocol) server that wraps Amazon 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, 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 — 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):

uvx amazon-nova-act-mcp --configure

AWS/IAM setup (enterprise, AgentCore):

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:

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.

{
  "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:

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):

{
  "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:

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

Or in your MCP client config:

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

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

---