JetBrains MCP Proxy Server

The server proxies requests from client to JetBrains IDE, enabling seamless communication and multi-project development capabilities.

Install MCP Server plugin

https://plugins.jetbrains.com/plugin/26071-mcp-server

Recommended Version: 1.2.0+ for full multi-project support, WebSocket transport, cluster discovery, enhanced debugging tools, and GUI configuration features.

🚀 Quick Start

🔥 WebStorm连接步骤

1. 安装JetBrains MCP插件

• 在WebStorm中安装MCP Server Plugin (v1.2.0+)
• 确保至少有一个项目处于打开状态

2. 快速发现并连接WebStorm

# 自动发现并配置所有运行中的IDE（包括WebStorm）
npx @dddvchang/mcp-proxy mcp-find

3. 复制运行命令 系统会自动检测WebStorm并生成类似下面的连接命令：

claude mcp add proxy --name "webstorm" --proxy-command "npx" --proxy-args "@dddvchang/mcp-proxy" --proxy-env "MCP_SERVER_URL=ws://127.0.0.1:63331/api/mcp-ws/"

🎯 Automatic IDE Discovery & Configuration

The proxy now includes intelligent auto-discovery that automatically detects and identifies your JetBrains IDEs:

Enhanced Features:

• 🔍 Smart IDE Detection: Automatically identifies specific IDE types (IntelliJ IDEA, PhpStorm, DataGrip, etc.)
• 🚀 Port Range Scanning: Scans ports 63320-63340 for active MCP servers
• 🏷️ Descriptive Naming: Generates meaningful connection names instead of generic port numbers
• 📋 Ready-to-Use Commands: Outputs copy-paste ready claude mcp add commands
• 🔗 WebSocket Support: Uses WebSocket protocol for optimal performance

Example Output:

🔍 Scanning for JetBrains MCP servers (ports 63320-63340)...

✅ Found 4 MCP server(s):

   • Port 63331: IntelliJ IDEA Ultimate 2024.1.4
   • Port 63332: PhpStorm 2024.1.4  
   • Port 63333: DataGrip 2024.1.5
   • Port 63334: PyCharm Professional 2024.1.4

📋 To add these servers to Claude, run:

claude mcp add proxy --name "intellij-idea" --proxy-command "npx" --proxy-args "@dddvchang/mcp-proxy" --proxy-env "MCP_SERVER_URL=ws://127.0.0.1:63331/api/mcp-ws/"
claude mcp add proxy --name "phpstorm" --proxy-command "npx" --proxy-args "@dddvchang/mcp-proxy" --proxy-env "MCP_SERVER_URL=ws://127.0.0.1:63332/api/mcp-ws/"
claude mcp add proxy --name "datagrip" --proxy-command "npx" --proxy-args "@dddvchang/mcp-proxy" --proxy-env "MCP_SERVER_URL=ws://127.0.0.1:63333/api/mcp-ws/"
claude mcp add proxy --name "pycharm" --proxy-command "npx" --proxy-args "@dddvchang/mcp-proxy" --proxy-env "MCP_SERVER_URL=ws://127.0.0.1:63334/api/mcp-ws/"

✨ Done!

Supported IDEs:

• IntelliJ IDEA (Ultimate/Community)
• PhpStorm
• PyCharm (Professional/Community)
• WebStorm
• DataGrip
• CLion
• GoLand
• RubyMine
• Rider
• Aqua

Requirements:

• JetBrains IDE with MCP Server Plugin v1.2.0+
• At least one project open in each IDE

Tip: Use the get_all_open_projects tool after connecting to see which projects are available in each IDE.

🔧 Key API Usage Examples

Process Management Workflow

// 1. Start multiple services concurrently across different projects
// With smart queuing: if concurrent limit is 20, first 20 start immediately,
// remaining requests automatically queue and execute when slots become available
await Promise.all([
  callTool("run_configuration", { 
    configName: "API Gateway", 
    projectName: "gateway-project" 
  }),
  callTool("run_configuration", { 
    configName: "Auth Service", 
    projectName: "auth-service" 
  }),
  callTool("run_configuration", { 
    configName: "Message Service", 
    projectName: "message-service" 
  }),
  // ... can start 50+ services with automatic queuing
  callTool("run_configuration", { 
    configName: "User Service" 
    // No projectName = uses current project
  })
]);

// 2. Monitor services in real-time across projects
setInterval(async () => {
  const statuses = await Promise.all([
    callTool("get_process_status", { 
      configName: "API Gateway", 
      projectName: "gateway-project" 
    }),
    callTool("get_process_status", { 
      configName: "Auth Service", 
      projectName: "auth-service" 
    }),
    callTool("get_process_status", { 
      configName: "Message Service", 
      projectName: "message-service" 
    }),
    callTool("get_process_status", { 
      configName: "User Service" 
    })
  ]);
  console.log("Service statuses:", statuses);
}, 5000); // Check every 5 seconds

Multi-Project Development

// 1. List all open projects
const projects = await callTool("get_all_open_projects", {});

// 2. Search across all projects
const searchResults = await callTool("multi_project_search", { 
  searchText: "authentication logic" 
});

// 3. Direct project operations without switching (NEW!)
await Promise.all([
  callTool("run_configuration", { 
    configName: "Backend Services", 
    projectName: "backend-api" 
  }),
  callTool("run_configuration", { 
    configName: "Frontend Dev", 
    projectName: "frontend-app" 
  }),
  callTool("get_run_configurations", { 
    projectName: "microservice-auth" 
  })
]);

✨ New Features (v1.11.0+)

🏢 Multi-Project Support

• get_all_open_projects - List all currently open projects
• switch_project - Switch between different projects
• multi_project_search - Search across multiple projects
• multi_project_get_file - Read files from any project
• multi_project_run_config - Manage run configurations across projects

🚀 Enhanced Process Management

• run_configuration - Start services and processes (now returns quickly on startup)
  • Optional projectName parameter for direct cross-project execution
  • Smart queuing: Automatic queuing when concurrent limits reached
• get_process_status - Monitor running processes and console output in real-time
  • Optional projectName parameter for cross-project monitoring
• get_run_configurations - List run configurations from any project
  • Optional projectName parameter for querying specific projects
• Concurrent execution - Run multiple services simultaneously across different projects
• Real-time monitoring - Check service status and logs without blocking
• No switch required - Operate on multiple projects without switch_project
• GUI Configuration - Adjust performance settings in IDE preferences
• Queue Management - Smart request queuing with configurable limits and timeouts

📊 Enhanced Monitoring

• Real-time monitoring through MCP Monitor tool window
• Improved error handling for multi-project operations
• Enhanced logging for debugging multi-project workflows
• Support for concurrent process monitoring across multiple services

🎯 Claude Desktop快速连接

将以下配置添加到Claude Desktop配置文件中即可连接WebStorm：

配置文件位置:

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

简单配置（推荐）:

{
  "mcpServers": {
    "webstorm": {
      "command": "npx",
      "args": ["-y", "@dddvchang/mcp-proxy"]
    }
  }
}

指定端口和协议（高级配置）:

{  
  "mcpServers": {
    "webstorm": {
      "command": "npx",
      "args": ["-y", "@dddvchang/mcp-proxy"],
      "env": {
        "MCP_SERVER_URL": "ws://127.0.0.1:63331/api/mcp-ws/",
        "IDE_PORT": "63331",
        "HOST": "127.0.0.1"
      }
    }
  }
}

配置说明:

• MCP_SERVER_URL: WebSocket连接地址（推荐使用WebSocket协议 ws://）
• IDE_PORT: WebStorm的MCP服务器端口（通常是63331-63340范围）
• HOST: 服务器地址（本地使用127.0.0.1，远程连接使用相应IP）

配置完成后重启Claude Desktop，确保WebStorm已打开并安装了MCP插件。

VS Code Installation

For one-click installation, click one of the install buttons below:

Manual Installation

Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

{
  "mcp": {
    "servers": {
      "jetbrains": {
        "command": "npx",
        "args": ["-y", "@dddvchang/mcp-proxy"]
      }
    }
  }
}

Optionally, you can add it to a file called .vscode/mcp.json in your workspace:

{
  "servers": {
    "jetbrains": {
      "command": "npx",
      "args": ["-y", "@dddvchang/mcp-proxy"]
    }
  }
}

Usage with Claude Desktop

To use this with Claude Desktop, add the following to your claude_desktop_config.json. The full path on MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json, on Windows: %APPDATA%/Claude/claude_desktop_config.json.

Single IDE Instance (Default)

{
  "mcpServers": {
    "jetbrains": {
      "command": "npx",
      "args": ["-y", "@dddvchang/mcp-proxy"]
    }
  }
}

Multiple IDE Instances (Cluster Mode)

{
  "mcpServers": {
    "jetbrains": {
      "command": "npx",
      "args": ["-y", "@dddvchang/mcp-proxy"],
      "env": {
        "CLUSTER_DISCOVERY": "true",
        "LOAD_BALANCING_STRATEGY": "project_affinity",
        "LOG_ENABLED": "true"
      }
    }
  }
}

After installing the MCP Server Plugin, and adding the JSON to the config file, restart Claude Desktop, and make sure the Jetbrains product is open before restarting Claude Desktop.

🔍 First-Time Setup & IDE Discovery

Important: On first launch, the MCP proxy will automatically:

• Scan for IDE instances on your local network (ports 63342-63352)
• Detect MCP-enabled IDEs with the plugin installed
• Establish connections to available IDE instances
• Cache discovery results for faster subsequent connections

This means:

1. Claude Code will automatically discover and connect to your JetBrains IDE
2. No manual port configuration needed in most cases
3. Multiple IDE support - connects to all detected instances
4. Automatic reconnection if IDE restarts

Troubleshooting Discovery:

• Ensure your IDE has the MCP Server plugin installed and enabled
• Check that IDE is running before starting Claude Desktop/Claude Code
• For external access, enable "Accept external connections" in IDE debugger settings

💬 Natural Language Project Interaction Examples

Once connected, you can interact with your IDE projects using natural language in Claude Code:

Project Discovery & Navigation:

"Show me all open projects"
"Switch to the mmq-app project"
"What files are in the src folder of my backend project?"
"Find all TypeScript files in the frontend project"

Code Analysis & Search:

"Search for authentication logic across all my projects"
"Find where the user login is implemented in mmq-app"
"Show me all the API endpoints in my project"
"What are the main components in this React project?"

Running & Managing Services:

"Start the development server for mmq-app"
"Run all the microservices in my backend project"
"Check the status of my running services"
"Stop the Redis service and restart the API server"

Multi-Project Operations:

"Run the frontend dev server in project A and the API server in project B"
"Search for database connection code across all open projects"
"Get the running configurations from my microservices project"
"Monitor the logs of services running in different projects"

Development Workflow:

"Run the tests for the current project"
"Build the production version of my app"
"Show me the console output of the running server" 
"List all available run configurations in this project"

🚀 New Features

🔍 Cluster Discovery & Load Balancing

Automatically discover and balance requests across multiple IDE instances!

• Auto-discovery: Finds all IDE instances on your network automatically
• Load balancing: Intelligently routes requests using multiple strategies
• Project affinity: Routes project-specific requests to the right IDE
• Failover: Automatically switches to healthy nodes when one fails
• Performance: Up to 3x faster for multi-project operations

📖 Learn more about Cluster Discovery

🔄 Enhanced WebSocket Support

• Persistent connections: Better performance with WebSocket transport
• Automatic reconnection: Handles IDE restarts gracefully
• Connection pooling: Manages multiple IDE connections efficiently
• Real-time monitoring: Live connection health monitoring

Configuration

MCP Proxy Configuration

If you're running multiple IDEs with MCP server and want to connect to the specific one, add to the MCP server configuration:

"env": {
  "IDE_PORT": "<port of IDE's built-in webserver>"
}

By default, we connect to IDE on 127.0.0.1 but you can specify a different address/host:

"env": {
  "HOST": "<host/address of IDE's built-in webserver>"
}

To enable logging add:

"env": {
  "LOG_ENABLED": "true"
}

Performance Configuration (New in v1.13.0)

Configure performance settings directly in your IDE:

1. Open Settings (⌘,)
2. Navigate to Tools → MCP Plugin
3. Adjust Performance Settings:

Max concurrent run configurations: 50    (recommended for high-end machines)
Max output buffer size: 200000          (200KB per process)
Max console output size: 50000          (50KB console history)

4. Configure Queue Settings:

☑ Enable request queuing when concurrent limit reached
Max queue size: 20                      (requests waiting in queue)
Queue timeout: 60                       (seconds before timeout)

Recommended Settings by Machine Type:

• M4 Max / High-end: 50-80 concurrent, queuing enabled
• Standard laptop: 20-30 concurrent, queuing enabled
• Low-spec machine: 10-15 concurrent, queuing optional

❓ 常见问题

WebStorm无法连接？

问题1: WebStorm连接失败或找不到MCP服务器

解决方案:

1. 确认WebStorm已安装MCP Server Plugin (v1.2.0+)
2. 确认至少有一个项目在WebStorm中打开
3. 运行命令检查连接：npx @dddvchang/mcp-proxy mcp-find
4. 重启Claude Desktop和WebStorm

问题2: Node.js版本错误 Cannot find module 'node:path'

解决方案:

• 升级Node.js到18+版本
• 确认配置中的command指向正确的Node.js版本

Troubleshooting

Node.js Version Requirements

Problem: Error message: Cannot find module 'node:path'

Solution: MCP Proxy doesn't work on Node 16. Upgrade your Node.js installation to version 18 or later. Make sure that command in config points to the correct Node.js version. Try to use the full path to the latest version of NodeJS.

MacOS: Plugin Unable to Detect Node.js Installed via nvm

Problem: On MacOS, if you have Node.js installed through nvm (Node Version Manager), the MCP Server Plugin might be unable to detect your Node.js installation.

Solution: Create a symbolic link in /usr/local/bin pointing to your nvm npx executable:

which npx &>/dev/null && sudo ln -sf "$(which npx)" /usr/local/bin/npx

This one-liner checks if npx exists in your path and creates the necessary symbolic link with proper permissions.

Using MCP with External Clients or Docker Containers (LibreChat, Cline, etc.)

Problem: When attempting to connect to the JetBrains MCP proxy from external clients, Docker containers, or third-party applications (like LibreChat), requests to endpoints such as http://host.docker.internal:6365/api/mcp/list_tools may return 404 errors or fail to connect. Solution: There are two key issues to address:

1. Enable External Connections:

In your JetBrains IDE, enable "Can accept external connections" in the Settings | Build, Execution, Deployment | Debugger.

2. Configure with LAN IP and Port:

Use your machine's LAN IP address instead of host.docker.internal Explicitly set the IDE_PORT and HOST in your configuration Example configuration for LibreChat or similar external clients:

mcpServers:
  intellij:
    type: stdio
    command: sh
    args:
      - "-c"
      - "IDE_PORT=YOUR_IDEA_PORT HOST=YOUR_IDEA_LAN_IP npx -y @dddvchang/mcp-proxy"

Replace:

YOUR_IDEA_PORT with your IDE's debug port (found in IDE settings) YOUR_IDEA_LAN_IP with your computer's local network IP (e.g., 192.168.0.12)

Changelog

v1.13.4 (Latest)

• 📖 Enhanced Documentation: Added comprehensive IDE discovery and connection documentation
• 💬 Natural Language Examples: Added detailed examples for project interaction using natural language
• 🔍 First-time Setup Guide: Clear instructions for automatic IDE scanning and discovery
• 🎯 Claude Code Integration: Improved guidance for seamless Claude Code IDE connection

v1.13.0

• 🎛️ GUI Configuration: Full performance settings in IDE preferences
• 📊 Smart Queuing: Automatic request queuing when concurrent limits reached
• ⚙️ Real-time Control: Adjust concurrent limits without restarting IDE
• 🎯 Balanced Defaults: Default 20 concurrent runs (suitable for general machines, adjustable for high-end)
• 📈 Queue Management:
  • Configurable queue size and timeout
  • Enable/disable queuing per preference
  • Smart queue processing with automatic retry

v1.12.0

• 🎯 Direct Multi-Project Operations: Added optional projectName parameter to core tools
• 🚀 No Switch Required: Execute operations across projects without switch_project
• ⚡ True Concurrency: Run and monitor services across multiple projects simultaneously
• 🔧 Enhanced APIs:
  • run_configuration with projectName support
  • get_process_status with projectName support
  • get_run_configurations with projectName support

v1.11.0

• ✨ Enhanced Process Management: Improved run_configuration with quick startup (30s timeout vs 120s)
• 🆕 New API: Added get_process_status for real-time process monitoring and console output
• 🚀 Concurrent Execution: Support for running multiple services simultaneously
• 📊 Better Monitoring: Enhanced logging and error handling for process operations
• 🔧 Improved Console Output: Better extraction of console text from running processes

v1.10.0

• 🏢 Multi-project support with comprehensive project management APIs
• 📊 Enhanced monitoring dashboard and real-time status tracking
• 🔍 Cross-project search and file operations

How to build

1. Tested on macOS
2. brew install node pnpm
3. Run pnpm build to build the project