crucible

Crucible is a Ruby MCP server that exposes a rich set of browser automation tools built on Ferrum and headless Chrome. It provides 29 distinct tools grouped by navigation, interaction, extraction, cookies, sessions, downloads, and stealth, enabling AI agents to programmatically drive a browser, query page data, manage sessions, and control downloads with stealth capabilities to reduce bot detection. Typical usage starts by launching the Crucible server with sensible defaults; you can then issue tool calls such as navigate, click, type, get_content, screenshot, pdf, and evaluate to perform end-to-end browser automation. The server supports per-session handling, so you can run multiple independent browser contexts concurrently and manage them via the session parameter on each tool call.

To use Crucible, run the server and interact with its tool API from your agent or client. For example, you can navigate to a URL, wait for a DOM element, extract page content, and generate a screenshot or PDF. The Stealth tools allow you to enable or adjust stealth profiles to help evade bot detection in environments that scrutinize headless Chrome. Crucible also provides session management utilities to list, switch between, and close multiple browser sessions, enabling complex flows like multi-step sign-ins or parallel experiments within isolated contexts.

Prerequisites:

• Ruby (supported versions as per Crucible gem requirements)
• Bundler (optional if using Bundler workflow)
• Internet access to fetch gems

Install from RubyGems:

gem install crucible

Alternatively, install from source:

git clone https://github.com/joshfng/crucible.git
cd crucible
bundle install

Usage after installation:

• Run the server with the default settings (headless, 1280x720, 30s timeout):

crucible

• To customize behavior, pass CLI options such as --no-headless, --width, --height, --timeout, --chrome, and --error-level as described in the README.

If you prefer to install and run via Bundler in a Ruby project, you can add crucible to your Gemfile and bundle install, then require and start the server from your app code according to the gem's documentation.

Notes and tips:

• Crucible defaults to headless mode with a 30-second timeout and a moderate stealth profile; adjust these with CLI options as needed.
• If you run into browser executable path issues, use --chrome to explicitly specify the Chrome/Chromium binary path.
• Stealth mode is enabled by default to help evade bot-detection systems; you can switch profiles or disable stealth if your environment requires it.
• The server exposes a comprehensive set of tools across Navigation, Interaction, Extraction, Cookies, Sessions, Downloads, and Stealth. Use sessions to manage multiple browser contexts concurrently.
• When using Claude Code or other MCP clients, configure the mcpServers entry to point to the crucible executable and pass any necessary config flags via args.
• Ensure your environment has a compatible Chromium binary installed; on some systems, installing chromium or google-chrome via your package manager is sufficient.
• If you clone the repo and run from source, remember to run bundle install to fetch the gem dependencies.