Using Kapture with MCP Clients

This guide explains how to configure and use Kapture with Model Context Protocol (MCP) clients like Claude Desktop, Cline, and custom implementations.

{
  "mcpServers": {
    "kapture": {
      "command": "npx",
      "args": ["kapture-mcp-server", "bridge"]
    }
  }
}

{
  "cline.mcpServers": {
    "kapture": {
      "command": "npx",
      "args": ["kapture-mcp-server", "bridge"]
    }
  }
}

Understanding the Architecture

How Kapture Works

Key Components

1. MCP Server: Runs on port 61822, handles all MCP protocol communication
2. Bridge Mode: Translates between stdio (used by MCP clients) and WebSocket
3. Chrome Extension: Injects into DevTools, executes browser commands
4. WebSocket: Real-time bidirectional communication

Smart Server Management

The npx kapture-mcp-server command includes intelligent server detection:

• If no server is running: Starts a new server
• If server already exists: Shows connection info and exits gracefully
• Multiple clients can share the same server instance

Installation & Configuration

System Requirements

• Chrome, Brave, Edge, Opera, or Vivaldi browser
• Node.js 16+ (for npx)
• An MCP-compatible AI client

Configuration Options

Recommended: Bridge Command

{
  "mcpServers": {
    "kapture": {
      "command": "npx",
      "args": ["kapture-mcp-server", "bridge"]
    }
  }
}

This approach:

• Automatically manages server lifecycle
• Handles stdio↔WebSocket translation
• Works with all MCP clients
• Supports multiple simultaneous clients

Alternative: Local Installation

If you've cloned the repository:

{
  "mcpServers": {
    "kapture": {
      "command": "node",
      "args": ["/path/to/kapture/server/dist/index.js", "bridge"]
    }
  }
}

Advanced: Direct WebSocket

For custom integrations or manual server control:

1. Start server manually: npx kapture-mcp-server
2. Configure client:

   {
     "mcpServers": {
       "kapture": {
         "transport": "websocket",
         "url": "ws://localhost:61822/mcp"
       }
     }
   }

Configuration File Locations

Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

VS Code (Cline):

• Open Settings (Cmd+,)
• Search for "cline.mcpServers"
• Edit in settings.json

Available Tools

Kapture provides 19 tools organized into functional categories:

Navigation Tools

{
  tabId: "tab_1234567890",
  url: "https://example.com",
  timeout: 30000  // optional, ms
}

{
  tabId: "tab_1234567890"
}

{
  tabId: "tab_1234567890"
}

Interaction Tools

{
  tabId: "tab_1234567890",
  selector: "button.submit",  // CSS
  // OR
  xpath: "//button[contains(text(), 'Submit')]"
}

{
  tabId: "tab_1234567890",
  selector: ".dropdown-trigger"
}

{
  tabId: "tab_1234567890",
  selector: "#email",
  value: "user@example.com"
}

{
  tabId: "tab_1234567890",
  selector: "#country",
  value: "us"  // option value
}

{
  tabId: "tab_1234567890",
  key: "Control+a",  // Select all
  selector: "#editor",  // optional
  delay: 100  // optional ms
}

{
  tabId: "tab_1234567890",
  selector: "#search-input"
}

Information Tools

{
  tabId: "tab_1234567890",
  selector: ".chart",  // optional
  scale: 0.5,  // 0.1-1.0
  format: "webp",  // webp|jpeg|png
  quality: 0.85  // 0.1-1.0
}

{
  tabId: "tab_1234567890",
  selector: "article"  // optional
}

{
  tabId: "tab_1234567890",
  selector: "a.external-link",
  visible: "true"  // true|false|all
}

{
  tabId: "tab_1234567890",
  level: "error",  // optional
  limit: 100,  // optional
  before: "2024-01-01T00:00:00Z"
}

{
  tabId: "tab_1234567890",
  x: 500,
  y: 300
}

Tab Management Tools

{}  // no parameters needed

{
  tabId: "tab_1234567890"
}

{
  browser: "chrome"  // optional
}

{
  tabId: "tab_1234567890"
}

Important Tool Behaviors

MCP Resources

Resources provide read-only access to browser data:

Examples & Patterns

Basic Navigation and Interaction

// Get available tabs
const tabs = await callTool('list_tabs', {});
const tabId = tabs[0].tabId;

// Navigate to a website
await callTool('navigate', {
  tabId,
  url: 'https://example.com'
});

// Fill and submit a form
await callTool('fill', {
  tabId,
  selector: '#username',
  value: 'myuser@example.com'
});

await callTool('fill', {
  tabId,
  selector: '#password',
  value: 'secretpass123'
});

await callTool('click', {
  tabId,
  selector: 'button[type="submit"]'
});

Working with Dynamic Content

// Wait for element to appear
async function waitForElement(tabId, selector, maxAttempts = 10) {
  for (let i = 0; i < maxAttempts; i++) {
    const result = await callTool('elements', {
      tabId,
      selector,
      visible: 'true'
    });
    
    if (result.elements.length > 0) {
      return result.elements[0];
    }
    
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
  throw new Error(`Element ${selector} not found after ${maxAttempts} attempts`);
}

// Use it
const element = await waitForElement(tabId, '.dynamic-content');
await callTool('click', {
  tabId,
  selector: element.selector
});

Advanced Form Handling

// Handle custom dropdowns (not HTML select)
await callTool('click', {
  tabId,
  selector: '.custom-dropdown-trigger'
});

await new Promise(resolve => setTimeout(resolve, 500));

await callTool('click', {
  tabId,
  xpath: "//li[@role='option'][contains(text(), 'United States')]"
});

// Handle multi-step forms
async function fillMultiStepForm(tabId, formData) {
  // Step 1: Personal Info
  await callTool('fill', { tabId, selector: '#firstName', value: formData.firstName });
  await callTool('fill', { tabId, selector: '#lastName', value: formData.lastName });
  await callTool('click', { tabId, selector: 'button.next-step' });
  
  // Wait for next step
  await waitForElement(tabId, '#email');
  
  // Step 2: Contact Info
  await callTool('fill', { tabId, selector: '#email', value: formData.email });
  await callTool('fill', { tabId, selector: '#phone', value: formData.phone });
  await callTool('click', { tabId, selector: 'button.submit-form' });
}

Screenshot Automation

// Capture different parts of a page
async function capturePageSections(tabId) {
  const screenshots = {};
  
  // Full page
  screenshots.full = await callTool('screenshot', {
    tabId,
    scale: 0.3
  });
  
  // Specific sections
  const sections = ['header', 'main', 'footer'];
  for (const section of sections) {
    screenshots[section] = await callTool('screenshot', {
      tabId,
      selector: section,
      format: 'png',
      scale: 0.5
    });
  }
  
  return screenshots;
}

Console Monitoring

// Monitor for errors during automation
async function runWithErrorMonitoring(tabId, automation) {
  // Clear existing logs
  await callTool('console_logs', { tabId, limit: 1 });
  
  // Run automation
  await automation();
  
  // Check for errors
  const logs = await callTool('console_logs', {
    tabId,
    level: 'error',
    limit: 100
  });
  
  if (logs.logs.length > 0) {
    console.warn('Errors detected during automation:', logs.logs);
  }
  
  return logs.logs;
}

Troubleshooting

Common Issues

Performance Tips

1. Keep Kapture Panel Active: Click/hover operations perform better when Kapture panel is selected
2. Use Efficient Selectors: ID selectors are fastest, followed by class, then complex selectors
3. Batch Operations: Group related commands together
4. Add Strategic Delays: Some interactions need time to complete

Debugging Strategies

1. Use HTTP Endpoints

Access data directly via browser:

• http://localhost:61822/ - Server status
• http://localhost:61822/tabs - Tab list
• http://localhost:61822/tab/{tabId}/screenshot/view - View screenshot

2. Check Element Visibility

const elements = await callTool('elements', {
  tabId,
  selector: '.my-element',
  visible: 'all'
});

elements.forEach(el => {
  console.log(`${el.selector}: visible=${el.isVisible}`);
});

3. Monitor Console Output

Enable real-time console monitoring in your client to see browser errors as they happen.

Advanced Topics

Multiple AI Assistants

Custom MCP Client Integration

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { spawn } from 'child_process';

// Spawn the server with bridge
const proc = spawn('npx', ['kapture-mcp-server', 'bridge']);
const transport = new StdioClientTransport({
  command: proc
});

const client = new Client({
  name: 'custom-client',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

// Subscribe to notifications
client.on('notification', (notification) => {
  if (notification.method === 'kapture/console_log') {
    console.log('Browser console:', notification.params);
  }
});

// Use tools
const result = await client.callTool('navigate', {
  tabId: 'tab_1234567890',
  url: 'https://example.com'
});

Security Considerations

1. Localhost Only: Server only accepts connections from localhost
2. Tab Isolation: Each tab has a unique ID, preventing cross-tab access
3. No File System Access: Extension runs in browser sandbox
4. Command Validation: All inputs are validated before execution

Best Practices

1. Always Check Tab Status

const tabs = await callTool('list_tabs', {});
if (tabs.length === 0) {
  throw new Error('No tabs connected');
}

2. Handle Dynamic Content Gracefully

• Use polling for elements that load asynchronously
• Add delays after interactions that trigger animations
• Check visibility before interacting

3. Optimize Selectors

• Prefer IDs over classes
• Use specific selectors to avoid ambiguity
• Consider XPath for text-based selection

4. Error Recovery

async function safeClick(tabId, selector, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const result = await callTool('click', { tabId, selector });
    if (result.clicked) return result;
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
  throw new Error(`Failed to click ${selector} after ${retries} attempts`);
}

Summary