SHAFT MCP Server Setup Guide

What is SHAFT MCP?

SHAFT MCP is a Model Context Protocol (MCP) server that enables Claude Desktop to perform web automation tasks using the SHAFT Engine (a Selenium-based test automation framework). This gives Claude powerful browser automation capabilities including:

Core Features

Browser Control: Launch Chrome, Firefox, Safari, or Edge browsers
Element Interaction: Click, hover, type, clear, drag-and-drop elements
AI-Enhanced Element Detection: Find elements by natural language descriptions
Advanced Actions: JavaScript-based clicks, file uploads, cookie management
Browser Navigation: URL navigation, back/forward, refresh
Data Extraction: Get page source, element text, attributes, CSS values
Test Reporting: Generate detailed Allure test reports

Available MCP Tools

The server provides 25+ tools for web automation:

Browser Management:

driver_initialize - Launch browser (Chrome/Firefox/Safari/Edge)
driver_quit - Close browser
browser_navigate - Navigate to URL
browser_refresh - Refresh page
browser_navigate_back/forward - Browser history navigation
browser_maximize_window - Maximize browser window
browser_set_window_size - Set custom window size
browser_fullscreen_window - Set fullscreen mode

Element Interaction:

element_click - Click elements using locators (ID, CSS, XPath, etc.)
element_click_ai - Click elements using AI (natural language)
element_click_js - JavaScript-based clicking
element_double_click - Double-click elements
element_hover - Hover over elements
element_type - Type text into elements
element_type_ai - Type using AI element detection
element_append_text - Append text to existing content
element_clear - Clear text from input fields
element_drag_and_drop - Drag and drop between elements
element_drop_file_to_upload - File upload functionality

Data Extraction:

element_get_text - Get element text content
element_get_dom_attribute - Get DOM attributes
element_get_dom_property - Get DOM properties
element_get_css_value - Get CSS property values
element_is_displayed/enabled/selected - Check element states
browser_get_page_source - Get page HTML source
browser_get_current_url - Get current URL
browser_get_title - Get page title

Session Management:

browser_add_cookie - Add cookies
browser_get_cookie - Get specific cookie
browser_get_all_cookies - Get all cookies
browser_delete_cookie - Delete specific cookie
browser_delete_all_cookies - Clear all cookies
generate_test_report - Generate Allure test reports

Distribution

SHAFT MCP is available through multiple channels:

GitHub MCP Registry: Officially listed in the Model Context Protocol Registry as io.github.ShaftHQ/shaft-mcp
Maven Central: Available as a Java JAR at io.github.shafthq:SHAFT_MCP
GitHub Container Registry: Docker images available at ghcr.io/shafthq/shaft-mcp
Smithery.ai: Deploy via Smithery for hosted MCP server (see SMITHERY_DEPLOYMENT.md)

Deployment Options

SHAFT MCP supports two deployment modes:

1. Local Deployment (Claude Desktop)

Uses STDIO transport for direct integration with Claude Desktop application. See setup instructions below.

2. Remote Deployment (Smithery & Web)

Uses HTTP/SSE transport for web-based access and remote hosting platforms like Smithery.ai, Railway, Render, etc.

📖 For Smithery and remote deployment instructions, see the comprehensive Smithery Deployment Guide which includes:

Step-by-step Smithery deployment
Local testing with Docker
10+ alternative hosting platforms comparison
Configuration options and best practices

Prerequisites

Claude Desktop App (latest version)
Java 21 (OpenJDK 21.0.2 LTS or newer) - for JAR-based installation
OR Docker - for Docker-based installation
Maven (only if building from source)

Setup Instructions

You can install SHAFT MCP using either the JAR file or Docker container:

Option A: Using Docker (Recommended)

Close Claude Desktop completely if it's running
Pull the Docker image:

docker pull ghcr.io/shafthq/shaft-mcp:latest

Locate your Claude config file:
- Windows: C:\Users\{USERNAME}\AppData\Roaming\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Edit the config file and add the SHAFT MCP server configuration:

{
  "mcpServers": {
    "shaft-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/shafthq/shaft-mcp:latest"
      ]
    }
  }
}

Option B: Using JAR File

Step 1: Build the MCP Server

Navigate to your SHAFT_MCP repository directory:

cd /path/to/ShaftHQ/SHAFT_MCP

Build the project (this creates the JAR file):

mvn clean package -DskipTests -Dgpg.skip

This will create: target/SHAFT_MCP-9.4.20251116.jar

Step 2: Configure Claude Desktop

Close Claude Desktop completely if it's running
Locate your Claude config file:
- Windows: C:\Users\{USERNAME}\AppData\Roaming\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Edit the config file and add the SHAFT MCP server configuration:

{
  "mcpServers": {
    "shaft-mcp": {
      "command": "java",
      "args": [
        "-jar",
        "/FULL/PATH/TO/SHAFT_MCP/target/SHAFT_MCP-9.4.20251116.jar"
      ]
    }
  }
}

Important Notes:

Replace /FULL/PATH/TO/SHAFT_MCP/ with the actual absolute path to your repository
Ensure the JAR file version matches what was built (check the target/ directory)
Use forward slashes / even on Windows, or double backslashes \\\\ for Windows paths

Verify Installation

Start Claude Desktop
Check MCP Server Status:
- Go to File > Settings > Developer
- Look for shaft-mcp in the MCP servers list
- Confirm the status shows as running
Test the server with this prompt in Claude:

Use shaft-mcp to launch Chrome, navigate to google.com, search for "selenium webdriver", and get the page title.

Usage Examples

Once configured, you can use Claude to perform complex web automation tasks:

Basic Browser Control

Use shaft-mcp to:
1. Launch Firefox browser
2. Navigate to https://example.com
3. Get the page title and current URL

Element Interaction

Use shaft-mcp to:
1. Launch Chrome
2. Go to a login page
3. Find the username field and type "testuser"
4. Find the password field and type "testpass"
5. Click the login button

AI-Enhanced Element Detection

Use shaft-mcp to:
1. Open a browser and go to amazon.com
2. Click on the search box using AI
3. Type "laptop" in the search field
4. Click the search button using AI

Data Extraction

Use shaft-mcp to:
1. Navigate to a news website
2. Get all the article headlines
3. Extract the main content text
4. Generate a test report

Troubleshooting

Common Issues:

"No active browser session found"
- Always initialize a browser first using driver_initialize
MCP Server not running
- Verify the JAR file path is correct and absolute
- Check that Java 21 is installed and accessible
- Ensure Claude Desktop was restarted after config changes
Build failures
- Verify Java 21 is installed: java -version
- Ensure Maven is available: mvn -version
- Try cleaning first: mvn clean
Element not found errors
- Use AI-based element detection (element_click_ai, element_type_ai)
- Try different locator strategies (CSS, XPath, ID, etc.)
- Check if the element is visible with element_is_displayed

Advanced Configuration

You can add additional MCP servers alongside SHAFT MCP:

{
  "mcpServers": {
    "shaft-mcp": {
      "command": "java",
      "args": ["-jar", "/path/to/SHAFT_MCP-9.4.20251116.jar"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

What This Enables

With SHAFT MCP configured, Claude can:

Automate web testing - Run comprehensive test suites on web applications
Perform web scraping - Extract data from websites with complex interactions
Automate repetitive tasks - Fill forms, upload files, navigate workflows
Generate test reports - Create detailed Allure reports with screenshots and logs
Cross-browser testing - Test across Chrome, Firefox, Safari, and Edge
AI-powered element detection - Find elements by description instead of technical locators

This essentially turns Claude into a powerful web automation assistant that can handle complex browser-based tasks that would normally require manual effort or custom scripting.

shaft-mcp

Documentation