amazon-nova-act-mcp 1.0.61.0

Stateful MCP server for Nova Act prompt iteration workflows

nova-act-mcp-server

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

---

Prerequisites

• 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

Install with AIM (Recommended)

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

uvx nova-act-mcp-server --configure

AWS/IAM setup (enterprise, AgentCore):

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:

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:

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

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

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

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.

---