JetBrains MCP Proxy Server

This repository is deprecated and no longer maintained. The core MCP functionality has been integrated directly into all IntelliJ-based IDEs starting from version 2025.2.

Instead of using this NPM package, use the built-in functionality which supports SSE and a JVM-based proxy for STDIO.

Migration: Refer to the official JetBrains documentation for instructions on using the built-in MCP server.

To connect Claude Desktop to your JetBrains IDE, add the proxy configuration to your claude_desktop_config.json file.

Config File Locations:

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

Configuration:

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

Important: After updating the config, restart Claude Desktop. Ensure your JetBrains product is already open before restarting Claude Desktop.

When using external clients like LibreChat or Cline, or running inside Docker, connections to host.docker.internal may fail with 404 errors.

Steps to resolve:

1. Enable External Connections: In your JetBrains IDE, go to Settings | Build, Execution, Deployment | Debugger and enable "Can accept external connections".
2. Use LAN IP instead of localhost: Use your machine's actual LAN IP address and explicitly set IDE_PORT and HOST.

Example configuration for external clients (YAML format):

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

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

You can install the proxy in VS Code using one-click buttons (available in the repository README) or by manually editing your settings.

Manual Installation (User Settings)

Add the following block to your VS Code User Settings (JSON) file (accessible via Ctrl + Shift + P -> Preferences: Open User Settings (JSON)):

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

Workspace Installation

Alternatively, you can add this to a .vscode/mcp.json file within your specific workspace:

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

The proxy server automatically discovers the JetBrains IDE endpoint using the following priority logic:

1. Explicit Port: If process.env.IDE_PORT is provided, it tests http://${HOST}:${IDE_PORT}/api. If this endpoint does not respond correctly to a /mcp/list_tools request, the server fails.
2. Cached Endpoint: If a previously successful endpoint is known, the server attempts to reuse it.
3. Port Scanning: If no port is specified and no valid cache exists, the server scans a range of ports from 63342 to 63352 (inclusive) at http://${HOST}:${port}/api until it finds a working endpoint.

The server refreshes this endpoint discovery every 10 seconds to handle IDE restarts or port changes.

You can customize the proxy behavior using environment variables in your MCP server configuration:

• IDE_PORT: Specify the port of the IDE's built-in webserver if running multiple IDEs.
• HOST: Specify the host/address of the IDE's built-in webserver (defaults to 127.0.0.1).
• LOG_ENABLED: Set to "true" to enable logging.

"env": {
  "IDE_PORT": "<port of IDE's built-in webserver>",
  "HOST": "<host/address of IDE's built-in webserver>",
  "LOG_ENABLED": "true"
}

If you encounter the error Cannot find module 'node:path', it means you are using an unsupported Node.js version.

Requirement: MCP Proxy requires Node.js 18 or later. Node 16 is not supported.

Solution: Upgrade Node.js to version 18+. Ensure the command in your configuration points to the correct Node.js executable. Using the full path to the latest Node.js installation is recommended.

If you use nvm (Node Version Manager) on MacOS, the MCP Server Plugin may fail to detect your Node.js installation.

Solution: Create a symbolic link in /usr/local/bin that points to your npx executable:

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

The JetBrains MCP Proxy Server uses environment variables to control its behavior and connection to the IDE. Use these variables to configure the host, port, and logging:

• HOST: The hostname to use when scanning for the IDE endpoint. Defaults to 127.0.0.1.
• IDE_PORT: If set, the server will attempt to connect directly to this port at http://${HOST}:${IDE_PORT}/api. If the port is incorrect, the server will throw an error.
• LOG_ENABLED: Set to true to enable logging. When enabled, logs are sent to stderr via the log() function.

The following environment variables are used by the proxy server:

export function log(...args: any[]) {
    if (LOG_ENABLED) {
        console.error(...args);
    }
}