kblood/MCPBrowserServer

MCPBrowserServer

A comprehensive Model Context Protocol (MCP) server for browser automation using Selenium WebDriver. This server provides AI agents with powerful web browsing capabilities including session management, tab control, navigation, and element interaction.

Features

🌐 Session Management

• Create and manage multiple browser sessions
• Switch between sessions seamlessly
• Persist session state between restarts
• Configurable browser options (headless, window size, timeouts)

📑 Tab Management

• Create, switch, and close tabs within sessions
• Track tab state (URL, title, loading status)
• Navigate between multiple tabs efficiently

🧭 Navigation

• Navigate to URLs with load time tracking
• Page refresh, back, and forward navigation
• Execute JavaScript code on pages
• Capture screenshots for debugging

🎯 Element Interaction

• Find elements using CSS selectors, XPath, ID, class, etc.
• Click elements, type text, get element properties
• Wait for elements to appear
• Scroll to elements and hover interactions

📊 Debugging & Information

• Comprehensive page information extraction
• Screenshot capture (in memory or saved to file)
• Detailed error reporting and logging
• Debug information for all operations

Requirements

• .NET 9.0 or later
• Chrome browser installed on the system
• ChromeDriver (automatically managed by NuGet package)

Installation

1. Clone or download the project
2. Build the project:

   dotnet build MCPBrowserServer.csproj
   

3. Publish the executable:

   dotnet publish -c Release --self-contained false -o publish
   

Configuration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "browser": {
      "command": "C:\\path\\to\\MCPBrowserServer\\publish\\MCPBrowserServer.exe",
      "args": []
    }
  }
}

Available Tools

Session Management

• create_session - Create a new browser session
• list_sessions - List all active sessions
• get_session - Get session details
• switch_session - Switch to a different session
• close_session - Close a session
• get_active_session - Get currently active session

Tab Management

• create_tab - Create a new tab
• list_tabs - List all tabs in a session
• get_tab - Get tab details
• switch_tab - Switch to a different tab
• close_tab - Close a tab
• get_active_tab - Get currently active tab
• rename_tab - Rename a tab

Navigation

• navigate - Navigate to a URL
• refresh - Refresh current page
• go_back - Go back in browser history
• go_forward - Go forward in browser history
• get_page_info - Get page information (URL, title, meta data)
• take_screenshot - Capture page screenshot
• execute_javascript - Execute JavaScript code

Element Interaction

• find_elements - Find elements on the page
• click_element - Click an element
• type_text - Type text into an element
• get_element_text - Get text from an element
• get_element_attribute - Get element attribute value
• wait_for_element - Wait for element to appear
• scroll_to_element - Scroll to an element
• hover_element - Hover over an element

Usage Examples

Basic Session Creation

# Create a new browser session
create_session("Main Session", headless=false, width=1920, height=1080)

# Navigate to a website
navigate("session-id", "https://example.com")

# Take a screenshot
take_screenshot("session-id", saveToFile=true)

Tab Management

# Create a new tab
create_tab("session-id", "Google Tab", "https://google.com")

# List all tabs
list_tabs("session-id")

# Switch to a specific tab
switch_tab("session-id", "tab-id")

Element Interaction

# Find search input and type
find_elements("session-id", "input[name='q']", "css")
type_text("session-id", "input[name='q']", "MCP browser automation")

# Click search button
click_element("session-id", "button[type='submit']", "css")

# Wait for results and get text
wait_for_element("session-id", ".search-results", "css", 10)
get_element_text("session-id", ".search-results", "css")

Browser Options

When creating sessions, you can configure:

• headless - Run browser without GUI (default: true)
• width / height - Browser window size (default: 1920x1080)
• pageLoadTimeoutSeconds - Page load timeout (default: 30)
• userAgent - Custom user agent string
• Additional Chrome options

Logging

Logs are written to %TEMP%/mcp-browser-server-log.txt for debugging purposes.

Session data is persisted to %TEMP%/mcp-browser-sessions.json.

Error Handling

All tools return structured JSON responses with:

• Success - Boolean indicating operation success
• Error - Error message if operation failed
• DebugInfo - Additional debugging information
• Timestamp - Operation timestamp

Architecture

The server is built with:

• Models: Data structures for sessions, tabs, and responses
• Services: Core business logic for browser and session management
• Tools: MCP tool implementations that expose functionality to AI agents

Building from Source

# Restore dependencies
dotnet restore

# Build project
dotnet build

# Run tests (if available)
dotnet test

# Publish executable
dotnet publish -c Release -o publish

Troubleshooting

1. Chrome not found: Ensure Chrome is installed and in PATH
2. Permission issues: Run with appropriate permissions for file access
3. Port conflicts: Each session uses a unique Chrome instance
4. Memory usage: Monitor memory usage with many concurrent sessions

Contributing

This MCP server demonstrates advanced browser automation patterns and can be extended with additional tools and functionality.

License

This project is provided as-is for educational and development purposes.