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:

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

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"]
    }
  }
}

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

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

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: