PsiMcpServer

PsiMcpServer is an MCP server implemented as an IntelliJ IDEA plugin that exposes PSI refactoring and navigation capabilities through the MCP protocol so Claude Desktop and other MCP clients can drive IDE-based refactorings from outside the IDE. It groups tools into Core Tools (works across JetBrains IDEs like IntelliJ IDEA, PHPStorm, WebStorm) and PHP-specific tools (PHPStorm-only). Core tools include rename_element, move_element, safe_delete, find_usages, list_project_files, get_file_contents, and get_element_info for inspecting and manipulating PSI elements. The PHP-specific tools move PHP classes with full reference updates (move_php_class) and batch_move_php_classes for bulk moves, along with automatic namespace and import adjustments. The server can also integrate with the PsiPhpCodeFixer plugin to apply code style fixes after moves. To use Claude Desktop with this server, you deploy the proxy JAR that bridges Claude Desktop to the MCP server exposed by the IDE, and configure Claude Desktop to connect to localhost at the port the server listens on.

Once running, the MCP tool window in the IDE shows the server status, lists all available tools grouped by category, and indicates PHP support availability. External clients can call the MCP methods by matching the tool identifiers (e.g., rename_element, move_element, find_usages, move_php_class) and receive structured responses about operation progress and results. For long-running operations, progress is reported in the IDE status area, and if PsiPhpCodeFixer is installed, you’ll see its status as available and the plugin will apply fixes after refactors.

To interact from an external client like Claude Desktop, point the client to the proxy as described in the Claude Desktop integration steps and use the corresponding tool identifiers to request refactorings or file inspections. The tools support typical refactoring workflows such as moving a class, updating namespaces, and adjusting references across the project, all while keeping the repository in a consistent state.

Prerequisites

• Java 21 or later and a compatible Gradle setup if building from source
• An IntelliJ IDEA-compatible IDE (e.g., IntelliJ IDEA, PHPStorm, WebStorm)

Install from a prebuilt plugin (recommended)

1. Open your JetBrains IDE.
2. Go to Plugins → Install Plugin from Disk...
3. Select the provided PsiMcpServer plugin ZIP (built as part of the repository's release process, e.g., PsiMcpServer-1.0.0.zip).
4. Restart the IDE to activate the plugin.

Build from source (advanced)

1. Ensure you have Java 21+ and Gradle 8.x installed or use the provided Gradle wrapper.
2. In the repository root, build the plugin: ./gradlew buildPlugin
3. The plugin ZIP will be created at build/distributions/PsiMcpServer-1.0.0.zip.
4. To build the proxy JAR used for Claude Desktop integration: ./gradlew :proxy:jar The proxy JAR will be at proxy/build/libs/proxy-1.0.0.jar.

Claude Desktop integration (proxy setup)

1. Copy the proxy JAR generated above to a location Claude Desktop can access, for example: cp proxy/build/libs/proxy-1.0.0.jar ~/Library/Application\ Support/Claude/mcp-proxy.jar
2. Configure Claude Desktop to connect to the MCP server on localhost and the port exposed by the IDE plugin (default 3000).
3. Start the PSI MCP Server from the IDE (Tools → PSI MCP → Start PSI MCP Server) or via the PSI MCP tool window.
4. In Claude Desktop, ensure the mcpServers entry points to the proxy command with the appropriate host/port, as shown in the example configuration in the README.

Verification

• After installation, verify the MCP tool window in the IDE shows server status as Running and lists the available tools.
• In Claude Desktop, ensure the proxy is connected and that the psi-mcp-server is available in the configured mcpServers block.

Tips and caveats:

• The MCP server runs inside the IDE as a plugin, not as a standalone daemon; the proxy enables Claude Desktop to communicate with it from outside the IDE.
• Default port is 3000 unless configured otherwise in the IDE settings under Tools → PSI MCP Server.
• PHP-specific tools (move_php_class and batch_move_php_classes) require PHPStorm or PHP support in the IDE; verify PHP support indicator in the tool window.
• If PsiPhpCodeFixer is installed, automatic code style fixes will be applied after PHP moves; the tool window will indicate Code Fixer availability.
• When moving PHP classes, the plugin performs internal reference updates, external reference updates, namespace restructuring, and progress reporting. Review the generated changes to confirm correctness, especially in large projects with complex autoloading.
• If you encounter connection issues with Claude Desktop, ensure the proxy JAR path is correct and the host/port in the Claude config match the IDE plugin’s exposed port.