An MCP extension for the Claude Desktop application that enables automation and integration.
Add automation capabilities to Claude Desktop through the Model Context Protocol (MCP) and use Claude Desktop as a model gateway for Claude Code, solving the fundamental WSL-Windows integration challenge.
This is a Claude Desktop Extension project that addresses the complex challenge of enabling seamless communication between Claude Desktop (running natively on Windows) and Claude Code (running in WSL Linux environment). It adds automation capabilities to Claude Desktop through the Model Context Protocol (MCP) and enables using Claude Desktop as a model gateway for Claude Code, with core communication between these different environments operational across the WSL-Windows boundary. The project includes documented fixes for ESM loading, JSON validation, path translation, and file monitoring issues that arise when bridging these two different execution environments.
This project addresses a fundamental challenge:
Claude Desktop: Running on Windows (native app)
Claude Code: Running in WSL (Linux subsystem)
Problem: They're on the same machine but in different operating environments
This explains everything about the project's architecture:
They were designed specifically for this WSL/Windows cross-boundary communication challenge:
/mnt/c/Users/dimas/)The "remote" bridge design isn't just for different machines - it's essential for WSL/Windows integration:
Windows Claude Desktop ←→ Shared Files ←→ WSL Claude Code
(Consumer) (Bridge) (Executor)
Windows Environment | WSL (Linux) Environment
--------------------------------- | ---------------------------
Claude Desktop (native app) | Claude Code (CLI)
↓ | ↑
MCP Server (Node.js) | ↑
↓ | ↑
Bridge Process (JS or Python) ←→ Shared Files/Directories ←→ WSL Integration
This architecture is specifically designed to handle the challenges of cross-environment communication, where two fundamentally different operating systems need to work together on the same physical machine:
/mnt/c/Users/...) accessible from both environmentsC:\path) and WSL paths (/mnt/c/path)Basic Extension Tier:
custom-claude-mcp.js or custom-claude-mcp-stdio.js) - Provides tools to Claude Desktopclaude-desktop-bridge.js or claude-desktop-bridge.py) - Monitors and executes actionsModel Gateway Tier:
dev-hub-mcp-server.js) - Routes Claude Code requestsclaude-desktop-gateway.js) - Interfaces with Claude Desktopsession-manager.js) - Handles authentication across appsClone this repository:
git clone https://your-repo-url/claude-desktop-extension.git
cd claude-desktop-extension
Install dependencies:
npm install
Update Claude Desktop configuration:
Edit %APPDATA%\Claude\claude_desktop_config.json to include the custom MCP server:
{
"mcpServers": {
"custom-extension": {
"command": "node",
"args": ["C:\\Users\\dimas\\Desktop\\Claude_Automation\\src\\custom-claude-mcp-stdio.js"],
"env": {},
"disabled": false
}
}
}
Start the services:
For the basic extension:
npm run start:all
For the Model Gateway (Claude Code integration):
npm run start:model-gateway
Or on Windows, simply run one of these batch files:
start.bat # Basic extension
start-model-gateway.bat # Model Gateway
For the most comprehensive setup (recommended):
.\start-claude-admin-with-monitoring.ps1
Launch Claude Desktop and it should connect to your custom MCP server
The project has two main configuration files:
Claude Desktop Extension: config/claude-config.json:
{
"mcpPort": 4323,
"toolsPort": 4322,
"logLevel": "info"
}
Model Gateway: config/dev-hub-config.json:
{
"port": 4323,
"browserToolsPort": 4322,
"heartbeatIntervalMs": 30000,
"logLevel": "info"
}
The system can be extended with plugins. See the plugins directory for examples:
file-operations-plugin.js: Adds file operation toolscode-to-desktop-plugin.js: Enables Claude Code to Claude Desktop communicationdesktop-to-code-plugin.js: Desktop to Code communicationTo create a plugin:
plugins directory✅ All components fully tested and operational ✅ Bidirectional communication confirmed ✅ WSL integration working ✅ Plugin system functional ✅ MCP server responding correctly ✅ JSON parsing errors completely resolved
custom-claude-mcp.js): Original implementationcustom-claude-mcp-stdio.js): JSON-error-free implementationsrc/
├── custom-claude-mcp.js # WebSocket-based MCP server
├── custom-claude-mcp-stdio.js # Stdio-based MCP server (✅ recommended)
├── claude-desktop-bridge.js # Bridge process (✅ working)
├── claude-desktop-gateway.js # Model gateway
├── dev-hub-mcp-server.js # Development tools MCP server
├── session-manager.js # Session management
└── *-client.js # Client utilities
plugins/
├── file-operations-plugin.js # File operation tools (✅ loaded)
├── code-to-desktop-plugin.js # Claude Code integration (✅ loaded)
└── desktop-to-code-plugin.js # Desktop to Code communication (✅ loaded)
config/
├── claude-config.json # Extension configuration
└── dev-hub-config.json # Model gateway configuration
requirements/
├── base.txt # Common dependencies for all environments
├── windows.txt # Windows-specific dependencies
├── wsl.txt # WSL-specific dependencies
├── dev.txt # Development dependencies
├── api.txt # Optional API integration dependencies
└── README.md # Dependency management guide
docs/
├── ARCHITECTURE.md # Architecture details
├── GATEWAY_ARCHITECTURE.md # Gateway architecture details
├── claude-desktop-bridge-guide.md # Bridge usage guide
├── claude-desktop-extension-schema.md # Extension schema
└── requirements.txt # Python requirements (legacy location)
open_conversation - Open specific conversations ✅switch_model - Change Claude Desktop model ✅update_mcp_config - Update MCP configuration ✅analyze_file - Analyze files in Claude Desktop ✅save_conversation - Save conversations to files ✅execute_from_code - Execute actions from Claude Code ✅send_to_claude_code - Send commands from Claude Desktop to Claude Code ✅notify_claude_code - Send notifications to Claude Code ✅get_claude_code_status - Check Claude Code responsiveness ✅request_project_info - Get project information from Claude Code ✅check_trigger_status - Check status of triggered actions ✅analyze_codebase - Comprehensive code analysisdebug_with_browser_context - Debug with browser dataanalyze_performance - Performance analysis with network monitoringcode_review - Enhanced code review with browser contextnpm run start:all or start.batnpm run start:model-gateway or start-model-gateway.bat.\start-claude-admin-with-monitoring.ps1.\start-claude-admin-with-monitoring.ps1 -StopThe start-claude-admin-with-monitoring.ps1 script provides a comprehensive solution for setting up and monitoring the entire Claude Desktop environment. This script:
-Stop parameter to close all processesNow uses Stdio-based MCP Server:
custom-claude-mcp-stdio.js instead of the WebSocket-based server# Main script parameters and admin elevation
param([switch]$Stop = $false)
# Admin elevation check and re-launch if needed
# Core functions
function Close-AllProcesses { ... } # Closes all processes and windows
function Start-LogMonitoring { ... } # Sets up real-time log monitoring
function Start-ClaudeDesktopWithMonitoring { ... } # Main start function
# Execution flow
if ($Stop) {
Close-AllProcesses # Stop all processes if -Stop parameter is provided
} else {
Start-ClaudeDesktopWithMonitoring # Start everything with monitoring
}
# Start everything with monitoring
.\start-claude-admin-with-monitoring.ps1
# Stop all processes and monitoring windows
.\start-claude-admin-with-monitoring.ps1 -Stop
Use the provided WSL toolkit for installing Claude Code:
Installation Script: install-claude-code-wsl.bat
Launcher: run-claude-code.bat
Launch Command:
c:\Users\dimas\Desktop\"CLAUDE CODE ToolKIT WSL Edition"\run-claude-code.bat
C:\Users\dimas\claude-bridge\ (Windows) = /mnt/c/Users/dimas/claude-bridge/ (WSL)claude-env.bat and authentication syncws - WebSocket communication ✅chokidar - File watching ✅node-fetch - HTTP requests ✅During plugin/tool initialization, the system encountered JSON parsing errors with the following error message:
Expected ',' or ']' after array element in JSON at position 5 (line 1 column 6)
This error prevented proper tool initialization in Claude Desktop, causing some plugins to fail loading and tools to be unavailable.
After thorough investigation and multiple approaches, we have completely resolved the JSON parsing errors. The logs now show no errors, and the system is functioning perfectly.
The true root cause was identified:
Created a proper stdio-based MCP server (custom-claude-mcp-stdio.js):
Updated communication protocol:
"transport": "stdio" and "port": nullAdded Tool Parameter Serialization and Validation:
function validateToolParameters(tool) {
try {
// Validate each parameter has proper structure
if (tool.parameters) {
// Deep clone and re-serialize to ensure valid JSON
const serialized = JSON.stringify(tool.parameters);
const deserialized = JSON.parse(serialized);
tool.parameters = deserialized;
}
return true;
} catch (error) {
console.error(`Tool parameter validation failed for ${tool.name}: ${error.message}`);
return false;
}
}
Enhanced Plugin Loading:
function loadPlugin(pluginPath) {
try {
const plugin = require(pluginPath);
if (!plugin.tools || !Array.isArray(plugin.tools)) {
console.error(`Plugin at ${pluginPath} does not export tools array`);
return [];
}
// Validate each tool in the plugin
return plugin.tools.filter(tool => {
if (!validateToolParameters(tool)) {
console.error(`Skipping tool ${tool.name} due to parameter validation failure`);
return false;
}
return true;
});
} catch (error) {
console.error(`Failed to load plugin at ${pluginPath}: ${error.message}`);
return [];
}
}
Installation:
cd Claude_Automation
npm install
Starting Services:
npm run start:all
Testing: Use test scripts in scripts/ directory ✅
Debugging: Check logs in logs/ directory ✅
Extensions: Add plugins to plugins/ directory ✅
Configuration: Update configs in config/ directory ✅
curl http://localhost:4323/.identity - SUCCESSClaude Desktop ←→ MCP Server ←→ Bridge Process ←→ File System ←→ Claude Code (WSL)
✅ All core components implemented and functional ✅ Bidirectional communication fully verified ✅ WSL integration tested and working ✅ Plugin system operational ✅ MCP protocol fully implemented ✅ Bridge process monitoring and processing ✅ Claude Desktop integration confirmed ✅ Claude Code WSL launch working ✅ Complete documentation available ✅ Ready for production use
This project includes a comprehensive suite of monitoring and debugging tools designed to provide complete, end-to-end visibility into the system. It is managed via a user-friendly batch file launcher, making it accessible regardless of your PowerShell experience.
If you are experiencing any issues, especially silent tool call failures, start here.
.\monitoring-tools.bat
[1] Live Tool Call Debugger.For any problem, follow these simple steps:
monitoring-tools.bat → Choose Option [6] (Validate All Scripts). This ensures no scripts are broken.monitoring-tools.bat → Choose Option [1] (Live Tool Call Debugger). This is your main window into the system.Our tools provide visibility at every critical step of the communication flow:
[Claude Desktop] -> [MCP Server] -> [Bridge Process] -> [WSL Claude Code]
▲ ▲ ▲ ▲
| | | |
(tool-call- (Port & Process) (File Activity) (WSL Process)
debugger) (system-monitor) (bridge-monitor) (system-monitor)
The system is comprised of several key components, all accessible from the main launcher:
monitoring-tools.bat (Main Launcher):
ExecutionPolicy so scripts run without hassle.scripts/tool-call-debugger.ps1 (Live Tool Debugger):
scripts/claude-system-monitor.ps1 (System-Wide Monitor):
scripts/bridge-monitor.ps1 (Bridge Communication Monitor):
claude-bridge and related directories, showing recent activity to diagnose communication stalls.scripts/validate-scripts.ps1 (Syntax Validator):
claude-master-control.ps1 (Master Controller):
start, stop, and debug actions to manage the entire environment.logs/mcp-server.loglogs/mcp-server-stdio.loglogs/bridge.log%APPDATA%\Claude\session_state.json%APPDATA%\Claude\logs\mcp-server-custom-extension.log%APPDATA%\Claude\logs\main.logThe start-claude-admin-with-monitoring.ps1 script automatically opens separate monitoring windows for:
This allows for real-time monitoring of all system components and simplified troubleshooting.
During the troubleshooting process, we used a variety of commands to manage services, check logs, and test functionality. Here's a comprehensive list of these commands for future reference:
Starting all services:
# From project root
npm run start:all
# Or using the batch file
.\start.bat
Starting only the model gateway:
npm run start:model-gateway
# Or using the batch file
.\start-model-gateway.bat
Stopping services:
# Find Node.js processes
Get-Process | Where-Object { $_.ProcessName -eq "node" }
# Kill specific Node.js process by ID
Stop-Process -Id <process_id>
# Kill all Node.js processes
Get-Process -Name "node" | Stop-Process
Restarting MCP server:
# Kill the MCP server process
Get-Process | Where-Object { $_.CommandLine -like "*custom-claude-mcp.js*" } | Stop-Process
# Start it again
node .\src\custom-claude-mcp.js
Viewing log files:
# MCP server log
Get-Content -Path .\logs\mcp-server.log -Tail 20 -Wait
# Bridge process log
Get-Content -Path .\logs\bridge.log -Tail 20 -Wait
# Claude Desktop extension logs
Get-Content -Path "$env:APPDATA\Claude\logs\mcp-server-custom-extension.log" -Tail 20 -Wait
Get-Content -Path "$env:APPDATA\Claude\logs\main.log" -Tail 20 -Wait
Clearing log files:
# Clear MCP server log
Clear-Content -Path .\logs\mcp-server.log
# Clear bridge log
Clear-Content -Path .\logs\bridge.log
Testing MCP server connection:
# Check if MCP server is responding
curl http://localhost:4323/.identity
# Expected response: {"name":"Claude Desktop Extension","version":"1.0.0"}
Creating test triggers for the bridge:
# Create a test trigger file
$triggerContent = @{
id = "test-trigger-$(Get-Date -Format 'yyyyMMddHHmmss')"
action = "test"
parameters = @{
message = "This is a test trigger"
}
} | ConvertTo-Json
# Save to the triggers directory
$triggerContent | Out-File -FilePath "$env:APPDATA\Claude\code_triggers\test-trigger.json"
Understanding the relationship between the different configuration files is crucial:
Claude Desktop Application Config:
%LOCALAPPDATA%\AnthropicClaude\config.jsonconfigPathClaude Desktop MCP Server Config:
%APPDATA%\Claude\claude_desktop_config.jsoncommand, args, env, and cwd settingsMCP Server's Internal Config:
claude-config.json)A critical issue we encountered was race conditions during MCP server startup:
EADDRINUSE errors on port 4323Error: listen EADDRINUSE: address already in use :::4323Based on our experience, here are best practices for developing Claude Desktop MCP extensions:
JSON Handling:
JSON.parse(JSON.stringify(obj)) to sanitize objects before transmissionPort Management:
Process Management:
npm install.\start-claude-admin-with-monitoring.ps1For some functionality, particularly when experiencing permission issues with file operations or plugin loading, running Claude Desktop as an administrator can resolve these problems.
Create a PowerShell script (run-claude-admin.ps1) with the following content:
# Request elevation if not already running as admin
if (-NOT ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")) {
Start-Process powershell.exe "-NoProfile -ExecutionPolicy Bypass -File `"$PSCommandPath`"" -Verb RunAs
exit
}
# Path to Claude Desktop executable
$claudePath = "${env:LOCALAPPDATA}\Claude\Claude.exe"
# Start Claude Desktop as admin
Start-Process -FilePath $claudePath
Run the script by right-clicking and selecting "Run with PowerShell".
This project consists of multiple components that work together to enable Claude Desktop and Claude Code integration.
| File | Purpose | Key Implementation Details |
|---|---|---|
| src/custom-claude-mcp.js | WebSocket MCP server | • Uses http, ws, fs, path, os, chokidar• Creates tools array from plugins• Updates session_state.json with server info |
| src/custom-claude-mcp-stdio.js | Stdio-based MCP server (✅ recommended) | • Uses readline interface with stdin/stdout• No console.log—all logging to file• Implements proper JSON validation |
| src/claude-desktop-bridge.js | Bridge process | • File watcher on code_triggers• Handles conversation saving• Process cleanup on exit |
| src/claude-desktop-gateway.js | Gateway for Claude Code | • Reads dev-hub-config.json• Creates request files with UUID• Uses file watching for communication |
| src/dev-hub-mcp-server.js | Development Hub MCP server | • Imports gateway functionality• Registers development tools• HTTP server on configured port |
| src/session-manager.js | Authentication manager | • Stores tokens in authenticated_sessions.json• Prunes expired sessions hourly• Provides token verification |
| src/dev-hub-client.js | Client for Dev Hub | • Minimal WebSocket wrapper• Promise-based tool calls |
| File | Purpose | Key Implementation Details |
|---|---|---|
| plugins/file-operations-plugin.js | File operation tools | • Tool for writing files with directory creation• ⚠️ No path sanitization (potential traversal risk) |
| plugins/code-to-desktop-plugin.js | Claude Code to Desktop integration | • Provides execute_from_code tool• Creates trigger files in code_triggers |
| plugins/desktop-to-code-plugin.js | Desktop to Code communication | • Tools for sending messages to Claude Code• Writes to code_responses directory |
| File | Purpose | Key Implementation Details |
|---|---|---|
| scripts/start-services.js | Starts core services | • Uses child_process.fork() for subprocess management• Implements lock file mechanism• Handles clean shutdown on SIGINT |
| scripts/start-model-gateway.js | Starts gateway services | • Forks dev-hub and gateway processes• No lock file implementation (potential race condition) |
| scripts/start-claude-admin-with-monitoring.ps1 | Complete setup with monitoring | • Elevates to admin privileges• Cleans up existing processes and ports• Sets up real-time log monitoring• Syncs WSL authentication |
| scripts/test-dev-hub.js | Tests Dev Hub functionality | • Hard-coded to connect to localhost:4324• Tests development tools |
| scripts/test-code-to-desktop.js | Tests Code to Desktop integration | • Creates test triggers• Checks trigger status with polling |
| scripts/update-claude-config.js | Updates Claude Desktop config | • Modifies claude_desktop_config.json• Creates backup before changes• ⚠️ Overwrites entire file (potential custom configuration loss) |
| scripts/sync-wsl-auth.js | Syncs WSL authentication | • Extracts tokens from WSL credentials• Creates shared environment variables |
| File | Purpose | Key Implementation Details |
|---|---|---|
| config/claude-config.json | MCP server configuration | • Defines port (4323)• Sets transport to stdio (recommended) |
| config/dev-hub-config.json | Dev Hub configuration | • Defines browser tools port (4322)• Used by dev-hub and gateway |
| File | Purpose | Key Implementation Details |
|---|---|---|
| python/claude-desktop-bridge.py | Python bridge implementation | • Uses watchdog for file monitoring• ⚠️ Windows-style path hard-coding• Legacy parity with JS bridge |
| python/claude-desktop-client.py | Python client | • Supports basic operations• ⚠️ Only works with WebSocket variant |
| File | Purpose | Key Implementation Details |
|---|---|---|
| start.bat | Starts extension services | • Simple wrapper for start-services.js• Requires Node on PATH |
| start-model-gateway.bat | Starts gateway services | • Wrapper for start-model-gateway.js• Same requirements as above |
| install-claude-code-wsl.bat | Installs Claude Code in WSL | • Targets Ubuntu-24.04• Sets up npm global directory• ⚠️ Fails silently if distribution missing |
| run-claude-code.bat | Launches Claude Code | • Probes multiple installation paths• Launches with --stdio flag |
The project includes comprehensive documentation in the docs/ directory:
Based on a comprehensive code review, the following issues and improvement opportunities have been identified:
Mixed stdout discipline: The stdio server properly avoids stdout, but plugins and bridge still use console.log, which could bleed into Desktop if hosted via stdio.
Path traversal risk: The file-operations plugin allows ../ traversal in file paths. Add a root whitelist or path.resolve guard.
Session manager integration: The session-manager.js appears underutilized. Consider better integration or removal.
Race condition protection: Lock file mechanism exists in start-services.js but not in all components. Standardize this approach.
Configuration overwriting: update-claude-config.js replaces the entire configuration file, potentially losing custom settings. Implement proper merging.
WSL distribution detection: Now more flexible with distribution naming, but could benefit from further parameterization.
Documentation updates needed: Several documentation files still reference WebSocket as default instead of stdio.
The most recent improvements to the codebase include:
Stdio transport adoption: Switched from WebSocket to stdio transport for more reliable communication.
JSON validation: Implemented robust JSON validation to prevent parsing errors.
WSL authentication synchronization: Added automatic WSL credential sharing.
Comprehensive monitoring: Created PowerShell script for complete setup with real-time log monitoring.
Lock file mechanism: Implemented process isolation to prevent multiple instance conflicts.
WSL distribution detection: Enhanced WSL Ubuntu detection to support various naming formats.
A complete changelog is available in the docs/CHANGELOG.md file.
This project includes Python scripts that are critical for solving the fundamental WSL-Windows boundary communication challenge.
The Python components (claude-desktop-bridge.py and related files) are essential infrastructure for specific use cases:
psutil library provides powerful cross-platform process control that works consistently in both environmentswatchdog library offers reliable file system event monitoring across the boundaryC:\path\to\file) and WSL (/mnt/c/path/to/file)src/utils/wsl module provides WSL interaction without external dependenciesThe Python scripts require specific dependencies listed in the requirements/ directory. To set up the environment:
# Install Python 3.9+ if not already installed
# Install dependencies
pip install -r requirements.txt
# For Windows-specific functionality
# This is automatically included when using requirements.txt
While the system has evolved to primarily use the JavaScript bridge (claude-desktop-bridge.js), the Python bridge (claude-desktop-bridge.py) remains important for certain scenarios:
To manually run the Python bridge:
# From the project root
python claude-desktop-bridge.py
The Python bridge will:
%APPDATA%\Claude\python-bridge\pending directorycompleted or failed directoriesNote: The PowerShell script
start-claude-admin-with-monitoring.ps1no longer directly launches the Python script, instead using the JavaScript bridge. The Python components are maintained for specific integration scenarios and as fallback mechanisms.
The system uses multiple communication methods to bridge the Windows-WSL boundary:
Interact with your Obsidian vault using natural language.
Tools for PostHog analytics, annotations, and project management.
Interact with Home Assistant to control smart home devices, query states, manage automations, and troubleshoot your smart home setup.
Reads EndNote .enl libraries and exposes their contents through the MCP interface.
Enables AI assistants to seamlessly interact with your Twenty CRM data through its API.
A server for querying Jira issues, requiring a Jira token for authentication.
Provides access to a specific user's memories from the Omi app.
Parses invoice data, uploads it to Google Sheets, and answers queries by fetching information from the sheet.
This server enables LLMs to use calculator for precise numerical calculations.
Interact with the HireBase Job API to manage job listings and applications.