{"id":45290526,"url":"https://github.com/n2ns/mcpxhub","last_synced_at":"2026-02-21T03:00:46.199Z","repository":{"id":283513146,"uuid":"950306003","full_name":"n2ns/MCPxHub","owner":"n2ns","description":"MCP middleware connecting Claude Desktop to VS Code, Cursor, JetBrains IDEs.","archived":false,"fork":false,"pushed_at":"2025-12-26T16:55:19.000Z","size":587,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-15T04:26:06.110Z","etag":null,"topics":["ai-coding","ai-tools","claude","claude-desktop","code-assistant","cursor","interoperability","jetbrains","mcp","mcp-server","middleware","nodejs","typescript","vscode","windsurf"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@bugstan/mcpxhub","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/n2ns.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-18T00:37:50.000Z","updated_at":"2025-12-30T13:14:23.000Z","dependencies_parsed_at":"2025-03-21T15:31:06.046Z","dependency_job_id":null,"html_url":"https://github.com/n2ns/MCPxHub","commit_stats":null,"previous_names":["bugstan/mcpxhub","n2ns/mcpxhub"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/n2ns/MCPxHub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n2ns%2FMCPxHub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n2ns%2FMCPxHub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n2ns%2FMCPxHub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n2ns%2FMCPxHub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/n2ns","download_url":"https://codeload.github.com/n2ns/MCPxHub/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n2ns%2FMCPxHub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29672241,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T00:11:43.526Z","status":"online","status_checked_at":"2026-02-21T02:00:07.432Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","ai-tools","claude","claude-desktop","code-assistant","cursor","interoperability","jetbrains","mcp","mcp-server","middleware","nodejs","typescript","vscode","windsurf"],"created_at":"2026-02-21T03:00:27.040Z","updated_at":"2026-02-21T03:00:46.193Z","avatar_url":"https://github.com/n2ns.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP x Hub: Universal MCP Bridge for Your IDE\n\n\u003e **Connect Claude Desktop to VS Code \u0026 JetBrains IDEs. Unlock Agentic Coding.**\n\n**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.\n\n[![npm version](https://img.shields.io/npm/v/@bugstan/mcpxhub.svg)](https://www.npmjs.com/package/@bugstan/mcpxhub)\n[![npm downloads](https://img.shields.io/npm/dt/@bugstan/mcpxhub.svg)](https://www.npmjs.com/package/@bugstan/mcpxhub)\n[![MCP Compliant](https://img.shields.io/badge/MCP-JSON--RPC%202.0-blue)](https://modelcontextprotocol.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003e **Current Version: v1.2.0**\n\n## 🚀 Why MCP x Hub?\n\nWhile 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.\n\n*   **⚡️ Universal Compatibility**: Works with **VS Code** and all its forks (**Cursor**, **Windsurf**, **Antigravity**) via [ggMCP4VSCode](https://github.com/bugstan/ggMCP4VSCode), as well as **JetBrains IDEs** (IntelliJ, PyCharm, WebStorm, etc.).\n*   **🔌 Zero-Config Connection**: Automatically detects active IDE ports. No manual IP/Port editing needed.\n*   **🛠 standard-compliant**: Full support for **MCP JSON-RPC 2.0**, ensuring reliable communication and error handling.\n*   **🔄 Auto-Reconnection**: Robustly handles IDE restarts without crashing your AI session.\n*   **🛡 Secure Proxy**: Forwards requests locally, keeping your code data on your machine.\n\n## 📖 Quick Start guide\n\nGet your AI Agent coding in minutes:\n\n1.  **Install MCP x Hub**:\n    ```bash\n    npm install -g @bugstan/mcpxhub\n    ```\n\n2.  **Install Your IDE Plugin**:\n    *   **VS Code**: [ggMCP4VSCode](https://github.com/n2ns/ggMCP4VSCode)\n    *   **JetBrains**: [MCP Server Plugin](https://github.com/n2ns/mcp-server-plugin)\n\n3.  **Configure Claude Desktop**:\n    Edit your `claude_desktop_config.json`:\n    ```json\n    {\n      \"mcpServers\": {\n        \"MCPxHub\": {\n          \"command\": \"npx\",\n          \"args\": [\"-y\", \"@bugstan/mcpxhub\"],\n          \"env\": {\n            \"IDE_TYPE\": \"vscode\" // or \"jetbrains\"\n          }\n        }\n      }\n    }\n    ```\n\n4.  **Start Coding**: Launch your IDE, then open Claude Desktop. They will connect automatically!\n\n---\n\n## ✨ Key Features\n\n*   **Smart Discovery**: Scans standard port ranges to find your active IDE (VS Code: 9960-9990, JetBrains: 63342-63352).\n*   **Parallel Port Scanning**: Uses advanced parallel scanning to detect your IDE instance instantly, even across large port ranges.\n*   **Live Tool Sync**: Detecting new tools or capabilities as you update your IDE plugins.\n*   **Protocol Compliance**: Implements the latest MCP JSON-RPC 2.0 specification for maximum compatibility with Claude 3.5 Sonnet and other models.\n*   **Resilient Connectivity**: Built-in \"Wait for IDE\" logic means you can start the tools in any order.\n\n## Required IDE Plugins\n\nMCP x Hub requires an MCP server plugin installed in your IDE to function:\n\n### VS Code Plugin\n- **Plugin**: [ggMCP4VSCode](https://github.com/n2ns/ggMCP4VSCode)\n- **Features**: Implements MCP server in VS Code, allowing communication with Claude Desktop through MCP x Hub\n\n### JetBrains Plugin\n- **Plugin**: [MCP Server Plugin](https://github.com/n2ns/mcp-server-plugin)\n- **Compatible IDEs**: IntelliJ IDEA, WebStorm, PyCharm, PhpStorm, and other JetBrains IDEs\n- **Features**: Implements MCP server in JetBrains IDEs, enabling Claude integration\n\n## Installation\n\n### NPM Package (Recommended)\n```bash\n# Global installation\nnpm install -g @bugstan/mcpxhub\n\n# Or as a project dependency\nnpm install @bugstan/mcpxhub\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/n2ns/MCPxHub.git\ncd MCPxHub\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n## Building the Project\n\n```bash\nnpm run build\n```\n\n## Bundling into a Single File\n\n```bash\nnpm run bundle\n```\n\nThe bundled file will be located at `dist/bundle.js`.\n\n## Local Testing\n\n### Method 1: Using Test Script\n\n#### Linux/macOS\n```bash\n# Give execution permission to the script\nchmod +x test.sh\n\n# Run test script\n./test.sh [ide_type]\n\n# Example:\n./test.sh jetbrains\n```\n\n#### Windows\n```cmd\n# Run test script\ntest.bat [ide_type] [mcp_server_port] [mcp_server]\n\n# Example:\ntest.bat jetbrains 63342 127.0.0.1\n```\n\n### Method 2: Manual Environment Variables\n\nThe `.claude.example.json` file in this repository contains a sample configuration for Claude Desktop. For manual testing with environment variables:\n\n1. Set environment variables directly:\n\n```bash\n# Enable logging\nexport LOG_ENABLED=true\n# Set IDE type ('jetbrains' or 'vscode')\nexport IDE_TYPE=jetbrains\n# Optionally specify MCP server address\n# export MCP_SERVER=127.0.0.1\n# Optionally specify MCP server port\n# export MCP_SERVER_PORT=63342\n```\n\n2. Run the bundled application:\n\n```bash\nnode dist/bundle.js\n```\n\n## Automatic Reconnection Feature\n\nMCP x Hub now includes an automatic reconnection mechanism with adaptive polling:\n\n- Even if IDE is not started yet when MCP x Hub starts, the program will continue running and wait for IDE to start\n- **Adaptive polling**: 5 seconds when disconnected (quick reconnection), 30 seconds when stable (reduced overhead)\n- Continuously attempts to connect without timeout, ensuring stability even if the IDE starts late\n- If connection was previously successful but later disconnected, uses fast recovery to reconnect immediately\n- Displays friendly status messages during reconnection process\n\nThis means you can start MCP x Hub and IDE in any order, and the system will automatically establish a connection.\n\n## Environment Variable Configuration\n\n| Variable Name   | Description        | Default Value |\n|-----------------|--------------------|---------------|\n| LOG_ENABLED     | Enable log output  | false         |\n| MCP_SERVER      | MCP server address | 127.0.0.1     |\n| IDE_TYPE        | IDE type           | jetbrains     |\n| MCP_SERVER_PORT | MCP server port    | None          |\n\n## Port Ranges\n\n- JetBrains IDE: 63342-63352\n- VS Code: 9960-9990\n\n## Connection Priority\n\n1. MCP_SERVER_PORT (if set) - Checks the specific port provided\n2. Cached endpoint - Reuses previously successful connection \n3. Scan port range based on IDE_TYPE:\n   - For jetbrains: Ports 63342-63352\n   - For vscode: Ports 9960-9990\n4. If IDE_TYPE is invalid or not set, tries JetBrains port range (63342-63352) as default\n\n## Troubleshooting\n\n1. If connection fails, ensure IDE is running with MCP Server plugin installed\n2. Check if firewall allows access to specified ports\n3. Enable LOG_ENABLED=true to see detailed logs\n4. For JetBrains IDE, default port is 63342\n\n## Technical Documentation\n\nFor detailed technical information, development guidelines, and integration instructions, see the docs directory.\n\n## Contributing\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn2ns%2Fmcpxhub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn2ns%2Fmcpxhub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn2ns%2Fmcpxhub/lists"}