Content
# 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](https://pi.dev).
`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 `<endpoint>__<tool>` 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:
```json
{
"type": "streamable-http",
"url": "http://127.0.0.1:64342/stream"
}
```
The port changes when the IDE restarts.
## Installation
### From the pi package gallery
```bash
pi install npm:@giuseppe.trisciuoglio/pi-jetbrains-mcp
```
### From GitHub
```bash
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
```bash
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:
```bash
ln -s "$PWD" ~/.pi/agent/extensions/jetbrains-mcp
```
## Quick start
After installing the package, add the MCP endpoint shown by your IDE:
```text
/jetbrains add-endpoint phpstorm http://127.0.0.1:64342/stream
```
Then verify the connection:
```text
/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:
```text
/jetbrains set-url phpstorm http://127.0.0.1:<new-port>/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:
```json
{
"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:
```json
{
"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 <id>` | Add the endpoint to the project selection (effective from the next session if not already active). |
| `/jetbrains unuse <id>` | 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:
```bash
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:
```json
{
"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 <id> <url>` | Persist a new endpoint URL, reconnect, and refresh its tools. |
| `/jetbrains add-endpoint <id> <url>` | Persist a new endpoint, connect to it, and register its tools. |
| `/jetbrains tools` | List live registered tools grouped by endpoint. |
| `/jetbrains use <id>` | Add the endpoint to this project's selection (`.pi/jetbrains.json`). |
| `/jetbrains unuse <id>` | 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 <id> <url>`. |
| Tools are missing | Confirm that MCP Server is enabled and run `/jetbrains reconnect <id>`. |
| 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 <id> <url>` or create `config.json` from the example. |
## Development
```bash
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).
Connection Info
You Might Also Like
No recommendations available