nova-act-mcp-server

nova‑act‑mcp‑server is a zero‑install Model Context Protocol (MCP) server that exposes Amazon Nova Act browser‑automation tools for AI agents.

What's New in v3.2.0

• File-Based Screenshots: Screenshots now save to files instead of inline base64, eliminating MCP message size limits
• Optimized Image Quality: Reduced screenshot quality (60/30) for smaller file sizes (~50KB vs 500KB+)
• Enhanced Error Handling: Improved exception handling for browser operations
• Better Testing: Comprehensive test coverage for screenshot functionality
• MCP Inspector Integration: New testing script for easy validation

Quick Start (uvx)

Step 1: Get a Nova Act API Key

Obtain your API key from Nova Act.

Step 2: Add to MCP Client Configuration

{
  "mcpServers": {
    "nova_act_browser_tools": {
      "command": "uvx",
      "args": ["nova-act-mcp-server"],
      "env": { "NOVA_ACT_API_KEY": "YOUR_NOVA_ACT_API_KEY_HERE" }
    }
  }
}

Step 3: Start Using Browser Tools

AI agents can now call tools like start_session, execute_instruction, etc. through any MCP-compatible client such as Claude Desktop or VS Code.

Core Tools Overview

Tool	Description	Key Parameters
start_session	Starts a new browser session	url, headless=True
execute_instruction	Runs a natural language instruction in the browser	session_id, instruction
inspect_browser	Gets a screenshot and state of the current browser	session_id, include_screenshot=True
end_session	Closes a browser session and cleans up resources	session_id
list_browser_sessions	Lists all active browser sessions	None

Local Development & Testing

Setup

# Clone the repository
git clone https://github.com/madtank/nova-act-mcp.git
cd nova-act-mcp

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with development dependencies
uv pip install -e .[dev]

Running Tests

# Run all tests (integration tests require NOVA_ACT_API_KEY)
pytest

# Run only unit tests (no API key required)
pytest tests/unit

# Run integration tests (requires API key)
NOVA_ACT_API_KEY="your_key_here" pytest tests/integration

Running Locally with MCP Inspector UI

# Start the server with the MCP Inspector
npx @modelcontextprotocol/inspector -e PYTHONUNBUFFERED=1 -e NOVA_ACT_API_KEY="YOUR_KEY" -- python -m nova_mcp_server

Then visit http://localhost:6274 in your browser. For optimal experience, set the Inspector UI timeout to 60 seconds for start_session operations.

Advanced Tools

Tool	Description
fetch_file	Downloads a file from the current page
view_html_log	Gets the HTML content of the current page
compress_logs	Creates and returns a ZIP of session logs and screenshots

License

MIT