Pi Jetbrains Mcp

JetBrains MCP for pi

[](https://github.com/giuseppe-trisciuoglio/pi-jetbrains-mcp/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@giuseppe.trisciuoglio/pi-jetbrains-mcp) [](LICENSE) [](https://pi.dev/packages)

> Connect one or more JetBrains IDE MCP Server endpoints and use their tools directly from pi.

pi-jetbrains-mcp turns every tool exposed by the JetBrains IDE MCP Server into a native pi tool. It supports several running IDEs at once, including IntelliJ IDEA, PhpStorm, WebStorm, PyCharm, and GoLand. Each endpoint has a stable identifier, so tool names are prefixed as __ and never collide.

Features

• Connect to multiple JetBrains IDE MCP Server endpoints in the same pi session.
• Discover and register MCP tools dynamically when pi starts or an endpoint reconnects.
• Keep tool names unambiguous with stable endpoint prefixes such as phpstorm__rename_symbol.
• Isolate endpoint failures: an unavailable IDE does not prevent other IDEs from working.
• Update an IDE's changing MCP port without restarting pi.
• Preserve structured MCP results, text output, and image content.
• Safely report tools that disappeared after an IDE reload.

Requirements

• pi 0.80.0 or later
• Node.js 22.19.0 or later
• One or more running JetBrains IDEs with MCP Server enabled

Recent JetBrains IDEs expose the server under Settings | Tools | AI Assistant | Developer. Enable MCP Server, then copy the streamable HTTP URL shown by the IDE. It normally looks like this:

{
  "type": "streamable-http",
  "url": "http://127.0.0.1:64342/stream"
}

The port changes when the IDE restarts.

Installation

From the pi package gallery

pi install npm:@giuseppe.trisciuoglio/pi-jetbrains-mcp

From GitHub

pi install git:github.com/giuseppe-trisciuoglio/pi-jetbrains-mcp@v1.1.0

Restart pi or run /reload after installation. The package is installed globally by default. Add -l to install it only for the current project.

Development checkout

git clone https://github.com/giuseppe-trisciuoglio/pi-jetbrains-mcp.git
cd pi-jetbrains-mcp
npm install
pi -e .

To make a checkout available to every pi session during development, symlink it into pi's extensions directory:

ln -s "$PWD" ~/.pi/agent/extensions/jetbrains-mcp

Quick start

After installing the package, add the MCP endpoint shown by your IDE:

/jetbrains add-endpoint phpstorm http://127.0.0.1:64342/stream

Then verify the connection:

/jetbrains
/jetbrains tools

The discovered tools are immediately available to pi. For example, a PhpStorm tool named rename_symbol becomes phpstorm__rename_symbol.

When the IDE restarts, update its endpoint and reconnect it:

/jetbrains set-url phpstorm http://127.0.0.1:/stream

Configuration

The extension stores its local configuration in config.json beside the installed package. The file is intentionally excluded from Git and npm packages because it can contain local endpoints and optional HTTP headers.

You can configure endpoints entirely through /jetbrains add-endpoint and /jetbrains set-url. To create the file manually, copy [config.example.json](config.example.json) to config.json and edit it:

{
  "endpoints": [
    {
      "id": "phpstorm",
      "url": "http://127.0.0.1:64342/stream",
      "headers": {},
      "connectTimeoutMs": 10000
    },
    {
      "id": "idea",
      "url": "http://127.0.0.1:64399/stream"
    }
  ]
}

| Field | Required | Description | | --- | --- | --- | | id | Yes | Unique lowercase identifier matching ^[a-z][a-z0-9_]*$. It is used as the tool-name prefix. | | url | Yes | Full streamable HTTP MCP endpoint URL. | | headers | No | Additional HTTP request headers for that endpoint. | | connectTimeoutMs | No | Connection timeout in milliseconds. Defaults to 10000. |

Per-project endpoint selection

By default every configured endpoint is connected and all its tools are registered. To restrict a project to a subset of IDEs, create a .pi/jetbrains.json file at the project root listing the endpoint ids to use:

{
  "endpoints": ["phpstorm"]
}

The selection defines the visible perimeter for the whole session: only the selected endpoints are connected and only their tools are registered. The semantics of the file are:

• File missing — fallback: all globally configured endpoints are used.
• File present with an empty list — no endpoint is active for that project.
• Unknown id in the list — reported as a warning at boot and skipped; the other ids remain valid.

The file contains only ids, so it is safe to commit to version control; URLs and headers live exclusively in the global config.json.

Manage the selection from within a session:

| Command | Effect | | --- | --- | | /jetbrains use | Add the endpoint to the project selection (effective from the next session if not already active). | | /jetbrains unuse | Remove the endpoint from the project selection. | | /jetbrains unuse all | Empty the whole project selection: no JetBrains endpoint will be active from the next session. | | /jetbrains selection | Show the current selection mode and ids. |

Environment override

JETBRAINS_MCP_URL overrides the endpoint named default, or creates it when it does not exist:

JETBRAINS_MCP_URL=http://127.0.0.1:64342/stream pi

Legacy configuration

The former single-endpoint shape is migrated automatically the next time the extension loads:

{
  "url": "http://127.0.0.1:64342/stream"
}

It becomes an endpoints array with the identifier default.

Commands

| Command | Description | | --- | --- | | /jetbrains | Show every endpoint's URL, connection state, and live tool count. | | /jetbrains reconnect [id] | Reconnect one endpoint, or every endpoint when no identifier is supplied. | | /jetbrains disconnect [id] | Disconnect one endpoint or all endpoints. Registered tools report an offline error until reconnected. | | /jetbrains set-url | Persist a new endpoint URL, reconnect, and refresh its tools. | | /jetbrains add-endpoint | Persist a new endpoint, connect to it, and register its tools. | | /jetbrains tools | List live registered tools grouped by endpoint. | | /jetbrains use | Add the endpoint to this project's selection (.pi/jetbrains.json). | | /jetbrains unuse | Remove the endpoint from this project's selection. | | /jetbrains unuse all | Empty this project's selection: no endpoint active from the next session. | | /jetbrains selection | Show the project selection mode and selected ids. |

Behavior and limitations

• Endpoint connections run independently. If one IDE is not running, tools from connected IDEs remain available.
• pi does not provide an API to unregister tools. When an IDE no longer exposes a previously discovered tool, the extension marks it unavailable and returns a useful error until the endpoint is reconnected or pi is reloaded.
• Removing an endpoint requires removing it from config.json and running /reload.
• The extension accepts any valid JSON Schema it can map to TypeBox. Unsupported schema constructs fall back to permissive input so the MCP tool remains callable.
• Only install extensions from sources you trust. An extension runs with the same permissions as pi.

Troubleshooting

| Symptom | Resolution | | --- | --- | | Endpoint is unreachable | Start the IDE, copy its new MCP URL, then run /jetbrains set-url . | | Tools are missing | Confirm that MCP Server is enabled and run /jetbrains reconnect . | | Invalid endpoint identifier | Use lowercase letters, digits, and underscores, starting with a letter. | | Invalid MCP URL | Include the full scheme and path, for example http://127.0.0.1:64342/stream. | | No endpoints configured | Run /jetbrains add-endpoint or create config.json from the example. |

Development

npm install
npm test

pi loads TypeScript extensions directly, so no compilation step is necessary. During local development, edit the source and run /reload in pi.

Contributing

Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the development and pull-request workflow. Please report security vulnerabilities according to [SECURITY.md](SECURITY.md).

Changelog

See [CHANGELOG.md](CHANGELOG.md) for release notes.

License

This project is licensed under the [MIT License](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: giuseppe-trisciuoglio
• Source: giuseppe-trisciuoglio/pi-jetbrains-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.