FerrumMCP 🌐

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

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

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

✅ 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

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

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

gem install ferrum-mcp
ferrum-mcp start

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

➡️ Full installation guide

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

• 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

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

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

• 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

• 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

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

➡️ Complete API Reference

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

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

We welcome contributions! Please see our Contributing Guide for details.

Quick contribution checklist:

• 📖 Read CONTRIBUTING.md
• 🐛 Use issue templates for bugs
• ✨ Use feature request template
• ✅ Run tests: bundle exec rspec
• 📝 Update documentation
• 🎨 Follow RuboCop style

For security vulnerabilities, please email eth3rnit3@gmail.com. See SECURITY.md for our security policy.

FerrumMCP is released under the MIT License.

Built with:

• Ferrum - Ruby Chrome DevTools Protocol
• Model Context Protocol by Anthropic
• Whisper for CAPTCHA solving
• BotBrowser for anti-detection (optional)

• 📚 Documentation: docs/
• 💬 Discussions: GitHub Discussions
• 🐛 Issues: GitHub Issues
• 📧 Email: eth3rnit3@gmail.com

Made with ❤️ by Eth3rnit3

Back to Top