@bugstan/mcpxhub

MCP x Hub: Universal MCP Bridge for Your IDE

Connect Claude Desktop to VS Code & JetBrains IDEs. Unlock Agentic Coding.

MCP x Hub is the ultimate middleware bridge that seamlessly connects AI Assistants (like Claude Desktop) to your local development environment. By adhering to the Model Context Protocol (MCP), it empowers your AI to read files, execute terminal commands, and analyze code directly within VS Code, Cursor, Windsurf, Antigravity, and JetBrains IDEs.

Current Version: v1.2.0

🚀 Why MCP x Hub?

While Claude Desktop is powerful, it's isolated from your codebase. MCP x Hub bridges this gap. It acts as a smart gateway, auto-discovering your running IDE instances and proxying MCP tool calls securely.

• ⚡️ Universal Compatibility: Works with VS Code and all its forks (Cursor, Windsurf, Antigravity) via ggMCP4VSCode, as well as JetBrains IDEs (IntelliJ, PyCharm, WebStorm, etc.).
• 🔌 Zero-Config Connection: Automatically detects active IDE ports. No manual IP/Port editing needed.
• 🛠 standard-compliant: Full support for MCP JSON-RPC 2.0, ensuring reliable communication and error handling.
• 🔄 Auto-Reconnection: Robustly handles IDE restarts without crashing your AI session.
• 🛡 Secure Proxy: Forwards requests locally, keeping your code data on your machine.

📖 Quick Start guide

Get your AI Agent coding in minutes:

• Install MCP x Hub:

  npm install -g @bugstan/mcpxhub
  

• Install Your IDE Plugin:

  • VS Code: ggMCP4VSCode
  • JetBrains: MCP Server Plugin

• Configure Claude Desktop: Edit your claude_desktop_config.json:

  {
    "mcpServers": {
      "MCPxHub": {
        "command": "npx",
        "args": ["-y", "@bugstan/mcpxhub"],
        "env": {
          "IDE_TYPE": "vscode" // or "jetbrains"
        }
      }
    }
  }
  

• Start Coding: Launch your IDE, then open Claude Desktop. They will connect automatically!

✨ Key Features

• Smart Discovery: Scans standard port ranges to find your active IDE (VS Code: 9960-9990, JetBrains: 63342-63352).
• Parallel Port Scanning: Uses advanced parallel scanning to detect your IDE instance instantly, even across large port ranges.
• Live Tool Sync: Detecting new tools or capabilities as you update your IDE plugins.
• Protocol Compliance: Implements the latest MCP JSON-RPC 2.0 specification for maximum compatibility with Claude 3.5 Sonnet and other models.
• Resilient Connectivity: Built-in "Wait for IDE" logic means you can start the tools in any order.

Required IDE Plugins

MCP x Hub requires an MCP server plugin installed in your IDE to function:

VS Code Plugin

• Plugin: ggMCP4VSCode
• Features: Implements MCP server in VS Code, allowing communication with Claude Desktop through MCP x Hub

JetBrains Plugin

• Plugin: MCP Server Plugin
• Compatible IDEs: IntelliJ IDEA, WebStorm, PyCharm, PhpStorm, and other JetBrains IDEs
• Features: Implements MCP server in JetBrains IDEs, enabling Claude integration

Installation

NPM Package (Recommended)

# Global installation
npm install -g @bugstan/mcpxhub

# Or as a project dependency
npm install @bugstan/mcpxhub

From Source

# Clone the repository
git clone https://github.com/n2ns/MCPxHub.git
cd MCPxHub

# Install dependencies
npm install

# Build the project
npm run build

Building the Project

npm run build

Bundling into a Single File

npm run bundle

The bundled file will be located at dist/bundle.js.

Local Testing

Method 1: Using Test Script

Linux/macOS

# Give execution permission to the script
chmod +x test.sh

# Run test script
./test.sh [ide_type]

# Example:
./test.sh jetbrains

Windows

# Run test script
test.bat [ide_type] [mcp_server_port] [mcp_server]

# Example:
test.bat jetbrains 63342 127.0.0.1

Method 2: Manual Environment Variables

The .claude.example.json file in this repository contains a sample configuration for Claude Desktop. For manual testing with environment variables:

• Set environment variables directly:

# Enable logging
export LOG_ENABLED=true
# Set IDE type ('jetbrains' or 'vscode')
export IDE_TYPE=jetbrains
# Optionally specify MCP server address
# export MCP_SERVER=127.0.0.1
# Optionally specify MCP server port
# export MCP_SERVER_PORT=63342

• Run the bundled application:

node dist/bundle.js

Automatic Reconnection Feature

MCP x Hub now includes an automatic reconnection mechanism with adaptive polling:

• Even if IDE is not started yet when MCP x Hub starts, the program will continue running and wait for IDE to start
• Adaptive polling: 5 seconds when disconnected (quick reconnection), 30 seconds when stable (reduced overhead)
• Continuously attempts to connect without timeout, ensuring stability even if the IDE starts late
• If connection was previously successful but later disconnected, uses fast recovery to reconnect immediately
• Displays friendly status messages during reconnection process

This means you can start MCP x Hub and IDE in any order, and the system will automatically establish a connection.

Environment Variable Configuration

Variable Name	Description	Default Value
LOG_ENABLED	Enable log output	false
MCP_SERVER	MCP server address	127.0.0.1
IDE_TYPE	IDE type	jetbrains
MCP_SERVER_PORT	MCP server port	None

Port Ranges

• JetBrains IDE: 63342-63352
• VS Code: 9960-9990

Connection Priority

• MCP_SERVER_PORT (if set) - Checks the specific port provided
• Cached endpoint - Reuses previously successful connection
• Scan port range based on IDE_TYPE:
  • For jetbrains: Ports 63342-63352
  • For vscode: Ports 9960-9990
• If IDE_TYPE is invalid or not set, tries JetBrains port range (63342-63352) as default

Troubleshooting

• If connection fails, ensure IDE is running with MCP Server plugin installed
• Check if firewall allows access to specified ports
• Enable LOG_ENABLED=true to see detailed logs
• For JetBrains IDE, default port is 63342

Technical Documentation

For detailed technical information, development guidelines, and integration instructions, see the docs directory.

Contributing

Please see CONTRIBUTING.md for details on how to contribute to this project.

License

This project is licensed under the MIT License - see the LICENSE file for details.