FerrumMCP 🌐

A browser automation server for the Model Context Protocol (MCP), enabling AI assistants to interact with web pages through a standardized interface.

---

🚀 Quick Links

| Documentation | Description | |---------------|-------------| | Getting Started | Installation, setup, and first steps | | Docker Deployment | Complete Docker guide with Claude Desktop integration | | API Reference | Complete documentation of all 27+ tools | | Configuration | Environment variables and advanced configuration | | Troubleshooting | Common issues and solutions | | Deployment | Production deployment guide | | BotBrowser Integration | Anti-detection browser setup |

---

📖 Table of Contents

• What is FerrumMCP?
• Features
• Quick Start
• Documentation
• Tools & Capabilities
• Project Resources
• Contributing
• License

---

What is FerrumMCP?

FerrumMCP is a browser automation server that implements the Model Context Protocol (MCP) by Anthropic. It provides AI assistants with the ability to navigate websites, interact with elements, extract content, and perform complex browser automation tasks through a simple, standardized interface.

Key Benefits:

• 🤖 AI-Native Design: Purpose-built for AI assistants like Claude
• 🔄 Session-Based: Multiple concurrent browser sessions with isolated configurations
• 🌐 Multi-Browser: Support for Chrome, Edge, Brave, and BotBrowser
• 🧩 Smart Automation: Cookie banner detection and CAPTCHA solving (⚠️ experimental)
• 📦 Easy Deployment: Docker, systemd, or Kubernetes ready
• 🔌 Dual Transport: HTTP and STDIO for maximum compatibility

---

Features

Core Capabilities

✅ Session Management

• Create/manage multiple browser sessions
• Automatic cleanup (30min idle timeout)
• Custom browser configurations per session

✅ Navigation

• URL navigation with network idle detection
• Browser history (back/forward)
• Page refresh

✅ Interaction

• Click, hover, drag-and-drop
• Form filling with typing delays
• Keyboard input simulation
• Smart cookie banner acceptance (8 strategies, multi-language)
• AI-powered CAPTCHA solving (Whisper integration - ⚠️ experimental, under development)

✅ Extraction

• Text and HTML content extraction
• Screenshot capture (base64)
• Page metadata (title, URL)
• XPath-based text search

✅ Advanced

• JavaScript execution and evaluation
• Cookie management (get/set/clear)
• Shadow DOM querying
• Element attribute retrieval

Enterprise Features

🦾 BotBrowser Integration

• Anti-detection browser automation
• Fingerprint management with encrypted profiles
• Note: Requires valid trial/premium profiles (demo profiles cause session instability)

🔒 Security (v1.0+)

• Session limits
• Rate limiting
• Health check endpoint
• Non-root Docker user

📊 Observability

• File-based logging
• Health checks
• Metrics endpoint (planned)

---

Quick Start

Option 1: Docker (Recommended)

Standard Image (Chromium only):

docker pull eth3rnit3/ferrum-mcp:latest
docker run --security-opt seccomp=unconfined -p 3000:3000 eth3rnit3/ferrum-mcp:latest

BotBrowser Image (Anti-detection):

docker pull eth3rnit3/ferrum-mcp:botbrowser
docker run --security-opt seccomp=unconfined -p 3000:3000 \
  -v /path/to/bot_profiles:/profiles:ro \
  -e "BROWSER_BOTBROWSER=botbrowser:/opt/botbrowser/chrome:BotBrowser:Anti-detection browser" \
  -e "BOT_PROFILE_MACOS_1=/profiles/profile_1.enc:Profile 1:Trial profile 1" \
  eth3rnit3/ferrum-mcp:botbrowser

Option 2: Gem Installation

gem install ferrum-mcp
ferrum-mcp start

Option 3: From Source

git clone https://github.com/Eth3rnit3/FerrumMCP.git
cd FerrumMCP
bundle install
ruby bin/ferrum-mcp

➡️ Full installation guide

---

Documentation

Getting Started

| Guide | Description | |-------|-------------| | Installation | Docker, gem, and source installation | | Claude Desktop Setup | Integrate with Claude Desktop (STDIO) | | First Session | Create your first browser automation |

Configuration

| Topic | Link | |-------|------| | Environment Variables | Configuration Guide | | Multi-Browser Setup | Multi-Browser Config | | BotBrowser Integration | BotBrowser Guide | | Resource Discovery | Resource Config |

API Documentation

| Resource | Description | |----------|-------------| | API Reference | Complete tool documentation with examples | | Session Management | Create, list, and manage browser sessions | | Navigation Tools | URL navigation and history | | Interaction Tools | Click, fill forms, solve CAPTCHAs | | Extraction Tools | Get content, screenshots, metadata | | Advanced Tools | JavaScript, cookies, Shadow DOM |

Operations

| Guide | Description | |-------|-------------| | Troubleshooting | Common issues and solutions | | Deployment | Docker, K8s, systemd deployment | | Migration | Upgrade between versions |

---

Tools & Capabilities

FerrumMCP provides 27+ browser automation tools organized into 6 categories:

1. Session Management (4 tools)

• create_session - Create browser sessions with custom config
• list_sessions - List all active sessions
• get_session_info - Get detailed session information
• close_session - Manually close a session

2. Navigation (4 tools)

• navigate - Navigate to URLs
• go_back - Browser back button
• go_forward - Browser forward button
• refresh - Reload current page

3. Interaction (7 tools)

• click - Click elements
• fill_form - Fill form fields
• press_key - Keyboard input
• hover - Mouse hover
• drag_and_drop - Drag elements
• accept_cookies - Smart cookie banner detection (8 strategies)
• solve_captcha - AI-powered CAPTCHA solving (⚠️ experimental, under development)

4. Extraction (6 tools)

• get_text - Extract text content
• get_html - Get HTML content
• screenshot - Capture screenshots
• get_title - Get page title
• get_url - Get current URL
• find_by_text - XPath text search

5. Advanced (9 tools)

• execute_script - Run JavaScript
• evaluate_js - Evaluate JavaScript with return value
• get_cookies - Get browser cookies
• set_cookie - Set cookies
• clear_cookies - Clear cookies
• get_attribute - Get element attributes
• query_shadow_dom - Interact with Shadow DOM

6. MCP Resources (7 resources)

• ferrum://browsers - Discover configured browsers
• ferrum://user-profiles - Discover Chrome profiles
• ferrum://bot-profiles - Discover BotBrowser profiles
• ferrum://capabilities - Server capabilities

➡️ Complete API Reference

---

Project Resources

Development

| Resource | Link | |----------|------| | Contributing Guide | CONTRIBUTING.md | | Security Policy | SECURITY.md | | Changelog | CHANGELOG.md | | AI Development Guide | CLAUDE.md |

Community

| Platform | Link | |----------|------| | GitHub Issues | Report bugs | | GitHub Discussions | Ask questions | | Docker Hub | eth3rnit3/ferrum-mcp |

Links

| Resource | URL | |----------|-----| | Repository | https://github.com/Eth3rnit3/FerrumMCP | | Documentation | https://github.com/Eth3rnit3/FerrumMCP/tree/main/docs | | Releases | https://github.com/Eth3rnit3/FerrumMCP/releases | | RubyGems | https://rubygems.org/gems/ferrum-mcp |

---

Requirements

System Requirements

• Ruby: 3.2 or higher
• Browser: Chrome, Chromium, Edge, or Brave
• OS: Linux, macOS, or Windows

Optional Dependencies

• whisper-cli: For CAPTCHA solving
• BotBrowser: For anti-detection automation
• Docker: For containerized deployment

---

Contributing

We welcome contributions! Plea