DevLensPro MCP Server

MCP server that enables Claude Code to see DOM elements you're pointing at in your browser, plus manage tasks for fixing issues.

Prerequisites

Pro subscription required for full MCP server access. Get one at devlens.pro/dashboard/settings.

| Feature | Free | Pro | |---------|------|-----| | Chrome Extension | Yes | Yes | | Local task storage | Yes | Yes | | MCP Server for Claude | No | Yes | | API Tokens | No | Yes | | Cloud sync | No | Yes |

Installation

1. Get Your API Key

1. Sign up at devlens.pro
2. Upgrade to Pro in Settings
3. Create an API Token in Settings > API Tokens
4. Copy your token (starts with dlp_)

2. Configure Claude Code

Add to your ~/.claude/.mcp.json:

{
  "mcpServers": {
    "devlenspro": {
      "command": "npx",
      "args": ["-y", "@devlenspro/mcp-server", "start"],
      "env": {
        "DEVLENSPRO_API_KEY": "dlp_YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternative: Quick Install

npx @devlenspro/mcp-server config claude

Alternative: Claude Code CLI

claude mcp add devlenspro -- npx -y @devlenspro/mcp-server start
# Then set DEVLENSPRO_API_KEY in your environment

Usage

1. Install the DevLensPro Chrome extension
2. Configure Claude Code with the MCP server
3. Hold Option (Mac) or Alt (Windows) and click any element
4. Ask Claude: "What element am I pointing at?"

MCP Tools

get-pointed-element

Returns information about the currently pointed DOM element.

Parameters:

• textDetail (optional): 0 = none, 1 = visible, 2 = full (default)
• cssLevel (optional): 0-3, controls CSS detail level

Response:

{
  "tagName": "BUTTON",
  "id": "submit-btn",
  "classes": ["btn", "btn-primary"],
  "selector": "#submit-btn",
  "innerText": "Submit",
  "position": { "x": 100, "y": 200, "width": 120, "height": 40 },
  "url": "https://example.com",
  "timestamp": "2026-01-23T10:00:00.000Z"
}

list-tasks

List tasks from local DevLensPro storage.

Parameters:

• domain (optional): Filter by domain (e.g., "localhost-3000")
• status (optional): "pending" | "in_progress" | "completed" | "blocked" | "all"

Response:

{
  "totalPending": 2,
  "tasks": [
    {
      "domain": "localhost-3000",
      "id": "task_123",
      "title": "Fix button alignment",
      "status": "pending",
      "priority": "high",
      "url": "http://localhost:3000/dashboard"
    }
  ]
}

get-task

Get detailed information about a specific task.

Parameters:

• domain (required): The domain/project
• taskId (required): The task ID

create-task

Create a new task with full captured data.

Parameters:

• domain (required): Domain for the task
• title (required): Short description
• description (optional): Detailed description of the issue
• url (required): URL where the issue was found
• priority (optional): "low" | "medium" | "high" | "critical"
• userComment (optional): User comment about the fix
• userPrompt (optional): Instruction for Claude to fix
• element (optional): Full element data object:
  • selector, tagName, id, classes, attributes
  • innerText, textContent
  • position (x, y, width, height)
  • computedStyles
• screenshot (optional): Screenshot object with base64, width, height
• consoleMessages (optional): Array of console messages with level, message, timestamp

Example:

{
  "domain": "localhost-3000",
  "title": "Fix button alignment",
  "description": "Submit button is misaligned on mobile",
  "url": "http://localhost:3000/checkout",
  "priority": "high",
  "userPrompt": "Fix the submit button padding on mobile",
  "element": {
    "selector": "#submit-btn",
    "tagName": "BUTTON",
    "classes": ["btn", "btn-primary"],
    "innerText": "Submit Order",
    "position": { "x": 100, "y": 500, "width": 200, "height": 44 },
    "computedStyles": { "padding": "8px" }
  },
  "consoleMessages": [
    { "level": "error", "message": "404 Not Found", "timestamp": "..." }
  ]
}

### `update-task`

Update a task's status.

**Parameters:**
- `domain` (required): The domain/project
- `taskId` (required): The task ID
- `status` (optional): "pending" | "in_progress" | "completed" | "blocked"

### `complete-task`

Mark a task as completed.

**Parameters:**
- `domain` (required): The domain/project
- `taskId` (required): The task ID

### `list-projects`

List all DevLensPro projects with task summaries.

**Response:**
```json
{
  "totalProjects": 2,
  "projects": [
    {
      "domain": "localhost-3000",
      "summary": {
        "totalTasks": 5,
        "pendingTasks": 2,
        "completedTasks": 3
      },
      "lastUpdated": "2026-01-23T10:00:00.000Z"
    }
  ]
}

Modes

Local Mode (Default)

For when your browser and Claude Code run on the same machine:

npx @devlenspro/mcp-server start

The extension connects directly to ws://localhost:7007.

Cloud Mode

For when Claude Code runs on a remote server (VPS):

npx @devlenspro/mcp-server cloud --room YOUR_API_KEY

Generate a new API key:

npx @devlenspro/mcp-server generate-key

MCP config for cloud mode:

{
  "mcpServers": {
    "devlens": {
      "command": "npx",
      "args": ["-y", "@devlenspro/mcp-server", "cloud", "--room", "YOUR_API_KEY"]
    }
  }
}

Local Storage

Tasks are stored locally in ~/.devlens/:

~/.devlens/
├── config.json              # Global configuration
├── projects/
│   ├── localhost-3000/
│   │   └── stepper.json     # Tasks for this domain
│   └── example.com/
│       └── stepper.json
└── screenshots/             # Captured screenshots

How It Works

Browser Extension                    MCP Server
      │                                   │
      │  Option+Click on element          │
      │                                   │
      ├──── WebSocket message ────────────►
      │     {type: ELEMENT_POINTED}       │
      │                                   │
      │                            ┌──────┴──────┐
      │                            │ Process &   │
      │                            │ Store state │
      │                            └──────┬──────┘
      │                                   │
      │                            Claude Code
      │                                   │
      │                            ┌──────┴──────┐
      │                            │ MCP tool    │
      │                            │ call        │
      │                            └──────┬──────┘
      │                                   │
      │                            Returns element data

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | DEVLENSPRO_API_KEY | - | Required for Pro features. Get from dashboard. | | DEVLENSPRO_API_URL | https://handsome-mule-38.convex.site | API endpoint (don't change) | | DEVLENS_PORT | 7007 | WebSocket server port (local mode) | | DEVLENS_ROOM_ID | auto-generated | Room ID for cloud mode | | DEVLENS_RELAY_URL | wss://devlens-relay.partykit.dev | Cloud relay URL |

Troubleshooting

"DEVLENSPRO_API_KEY not set - Running in LOCAL-ONLY mode"

You haven't configured an API key. Local task management works, but cloud features are disabled.

Solution:

1. Get a Pro subscription at devlens.pro/dashboard/settings
2. Create an API token
3. Add DEVLENSPRO_API_KEY to your MCP config (see Installation above)

"Pro subscription required"

Your account is on the Free plan. MCP server requires Pro.

Solution:

1. Go to devlens.pro/dashboard/settings
2. Click "Upgrade to Pro"
3. Early adopters get 50% off!

"Invalid API key"

Your API key is incorrect or has been revoked.

Solution:

1. Go to devlens.pro/dashboard/settings
2. Delete the old token
3. Create a new API token
4. Update your ~/.claude/.mcp.json with the new key

"Subscription expired"

Your Pro subscription has ended.

Solution:

1. Go to devlens.pro/dashboard/settings
2. Click "Manage Subscription" to renew

CLI Commands

# Start MCP server (local mode)
npx @devlenspro/mcp-server start

# Start in cloud mode
npx @devlenspro/mcp-server cloud --room YOUR_KEY

# Generate new API key
npx @devlenspro/mcp-server generate-key

# Configure for Claude Code
npx @devlenspro/mcp-server config claude

# Configure for Cursor
npx @devlenspro/mcp-server config cursor

# Configure for Windsurf
npx @devlenspro/mcp-server config windsurf

# Full install with Ralph integration
npx @devlenspro/mcp-server install

Development

# Install dependencies
pnpm install

# Build
pnpm run build

# Run in development
pnpm run dev

add-fix-attempt

Record a fix attempt on a task.

Parameters:

• domain (required): The domain/project
• taskId (required): The task ID
• description (required): What was attempted
• success (required): boolean - whether it worked
• filesChanged (optional): Array of modified file paths

Example:

{
  "domain": "localhost-3000",
  "taskId": "task_123",
  "description": "Increased button padding from 8px to 16px",
  "success": true,
  "filesChanged": ["src/components/Button.tsx", "src/styles/buttons.css"]
}

Task Data Structure

Each task can contain:

| Field | Type | Description | |-------|------|-------------| | id | string | Unique task ID | | title | string | Short description | | description | string | Detailed description | | status | enum | pending, in_progress, completed, blocked | | priority | enum | low, medium, high, critical | | url | string | Page URL | | element | object | Full DOM element data | | screenshot | object | Captured screenshot | | consoleMessages | array | Console logs at capture | | userComment | string | User notes | | userPrompt | string | Fix instruction for AI | | fixAttempts | array | History of fix attempts |

Changelog

v1.3.0

• API Key validation: Pro subscription required for MCP server access
• Subscription validator: Validates API key at startup with 5-minute cache
• LOCAL-ONLY mode: Graceful degradation when no API key is set
• Clear error messages: Helpful instructions for subscription issues
• Dashboard integration: API key configuration in Settings page

v1.2.0

• Full element capture: tag, classes, attributes, innerText, position, computed styles
• Screenshot support: base64 data with local file storage
• Console capture: errors and warnings at task creation
• User prompts: store fix instructions for AI
• Fix tracking: add-fix-attempt tool to record fix history
• Rich get-task: returns all captured data with hints

v1.1.0

• Added task management tools: list-tasks, get-task, create-task, update-task, complete-task
• Added list-projects tool to see all tracked domains
• Local storage in ~/.devlens/ for offline task tracking

v1.0.3

• Initial stable release
• get-pointed-element tool with CSS detail levels

License

MIT