hechtcarmel/jetbrains-index-mcp-plugin

IDE Index MCP Server – What It Is

JetBrains Index MCP Server is a plugin for JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, GoLand, RustRover, Android Studio, PhpStorm, etc.) that starts a Model Context Protocol (MCP) server inside the IDE. The server listens on a local HTTP port (e.g., 127.0.0.1:29170 for IntelliJ) and exposes the IDE’s own code‑intelligence engine – its AST, symbol index, refactorings, diagnostics, build‑run tools – as a set of JSON‑based RPC calls.

AI coding assistants such as Claude, Codex, Cursor, and Windsurf can call these RPC methods, letting them:

• locate definitions, references, and hierarchies;
• run safe refactorings (rename, move, reformat, etc.);
• read files, search text, get diagnostics, and even trigger builds or tests;
• manage multiple projects (sleep/wake, open/close) to keep memory usage low.

In short, the plugin turns the IDE’s powerful, language‑aware features into a headless service that AI agents can use instead of relying on simple static‑analysis or fuzzy‑search tools.

---

Key Features (Jargon‑Light)

Area	What the plugin provides	Why it matters for AI assistants
Multi‑language support	Works with Java/Kotlin, Python, JavaScript/TypeScript, Go, PHP, Rust, Scala, Markdown (and any language that JetBrains already supports).	The same MCP endpoint can answer queries for many languages without extra configuration.
Universal tools	Find references, go to definition, search files/text, read diagnostics, sync the IDE’s virtual file system, trigger builds/tests, open/close projects, etc.	Gives the AI a true semantic view of the codebase, not just raw text.
Language‑aware refactorings	Safe rename, move file, reformat, optimize imports, edit/insert/replace members, change method signatures, Java‑to‑Kotlin conversion, etc.	AI can propose changes that are automatically applied without breaking references.
Project lifecycle management	Idle projects are automatically put to sleep, their PSI caches freed, and reopened on demand.	Keeps memory usage reasonable when the AI works across many repositories.
Headless / remote friendly	Server runs in normal IDE windows, JetBrains remote‑development sessions, or headless automation runs.	AI can be used from a container or CI job that talks to the local IDE.
Simple security model	Binds to 127.0.0.1 with no authentication; only processes on the same machine can call it.	Adequate for a single‑user workstation; users must decide if they need extra isolation on shared machines.

---

How It Works (High‑Level Architecture)

1. Plugin startup – When the IDE launches, the plugin starts an HTTP server bound to 127.0.0.1 on a default port that is unique per IDE (e.g., 29170 for IntelliJ, 29172 for PyCharm).
2. MCP request handling – Each request is a JSON payload describing a tool (e.g., ide_find_definition). The plugin forwards the request to the IDE’s internal APIs (PSI, index, refactoring engine) and returns a structured JSON response.
3. Tool window – A bottom‑panel UI shows the server’s status, lets you copy the configuration JSON, change the port, or enable/disable individual tools.
4. Client configuration – AI assistants are configured with a tiny JSON snippet that points to the local server URL. The README supplies ready‑made commands for Claude, Codex, Cursor, Windsurf, and generic VS Code MCP clients.
5. Lifecycle management – An optional background component monitors window focus and MCP activity, automatically putting idle projects into a low‑memory “dormant” state and waking them when a new MCP call arrives.

---

Who Might Use This?

Use case	Benefit
AI‑augmented coding – developers who let Claude or Codex suggest code and want the suggestions to be grounded in the exact project structure.	The AI can ask the IDE for the real definition of a symbol, get accurate diagnostics, and apply refactorings safely.
Automated code review / bulk refactoring – scripts that need to rename a class across a large multi‑module repo.	The plugin’s headless rename tool updates all references and respects language‑specific rules.
CI / testing pipelines – run static analysis or build steps via the IDE without launching a full UI.	ide_build_project and ide_run_tests expose the IDE’s build system in a machine‑friendly way.
Multi‑project workspaces – developers juggling dozens of Maven/Gradle projects.	Lifecycle management frees memory by sleeping projects that are not actively edited.

---

Getting Started (Quick Steps)

1. Install the plugin from the JetBrains Marketplace (or via the provided ZIP).
2. Restart the IDE – the MCP server starts automatically.
3. Open the "Index MCP Server" tool window and click "Install on Coding Agents". The button will either run the appropriate CLI command (Claude, Codex) or copy a JSON config for other clients.
4. In your AI assistant’s settings, add the server URL (e.g., http://127.0.0.1:29170/index-mcp/streamable-http).
5. Start coding – the assistant can now ask the IDE for definitions, run safe refactors, and read diagnostics.

---

Limitations & Security Note

• The server is local‑only and has no authentication. On a shared workstation, any process could invoke write‑capable tools (rename, move, edit). Consider disabling write tools or using OS‑level firewall rules if needed.
• Rider is not supported because its ReSharper backend does not expose the required PSI APIs.
• Some tools are disabled by default (e.g., ide_read_file, ide_refactor_rename). They must be enabled in Settings → Tools → Index MCP Server → Exposed Tools.

---

License & Contributions

The plugin is released under the standard JetBrains plugin license (see the repository’s LICENSE file). Contributions are welcome via pull requests; see the Contributing section of the repo for guidelines.

---

TL;DR

JetBrains Index MCP Server turns the IDE’s deep code‑understanding engine into a local HTTP service that AI coding assistants can call. It supports many languages, offers safe refactorings, project lifecycle management, and works with popular AI tools out‑of‑the‑box.