| name | idea-mcp |
| description | IntelliJ IDEA MCP for Java code analysis, testing, refactoring, and project navigation. Use when: (1) Checking Java compilation errors (get_file_problems is more accurate than LSP for multi-module Maven), (2) Performing rename refactoring across the codebase, (3) Searching code or finding files in the project. Requires IDEA to be running with MCP plugin connected.
|
IntelliJ IDEA MCP Skill
Path Rules (Most Common Error Source)
| Parameter | Path Type | Example |
|---|
projectPath | ABSOLUTE | /Users/huangli/dt/dongting |
filePath, pathInProject, directoryPath, contextPath | RELATIVE | server/src/main/java/... |
Getting this wrong is the #1 cause of "file not found" errors.
Gotchas and Tips
Two Search API Families
IDEA MCP has two sets of search tools that return different formats. Pick the right one:
search_in_files_by_text / search_in_files_by_regex — Returns matched lines with ||highlight|| markers. Good for quick "where is this string used" lookups. Supports fileMask filter.search_text / search_regex / search_file / search_symbol — Returns structured results with exact coordinates (line, column, byte offsets). Supports paths glob filters and ! excludes. Use this when you need precise locations for further operations.
search_symbol is especially powerful — semantic symbol lookup (classes, methods, fields) returning full code snippets.
execute_terminal_command Does Not Use Shell by Default
Without executeInShell: true, shell features like $() expansion, pipes, and wildcards won't work. For most shell commands, prefer the Bash tool directly.
rename_refactoring Takes Symbol Name, Not Position
Parameters are symbolName (the exact identifier string) and newName, not file path + line/column. This is different from LSP-based rename.
build_project for Single-File Compilation
build_project with filesToRebuild parameter compiles specific files much faster than running mvn compile. Useful for quick verification after edits.
get_file_problems vs LSP Diagnostics
For multi-module Maven projects, get_file_problems is significantly more accurate than LSP lsp_diagnostics. Prefer it for Java error checking.
High-Risk Operations
rename_refactoring & replace_text_in_file — Modify code globally, verify with get_file_problems after usereformat_file — Modifies formatting without confirmation
Troubleshooting
| Issue | Solution |
|---|
| Connection refused | Verify IDEA running with MCP plugin |
| Request timed out | Accept permission dialog in IDEA |
| File not found | Check absolute vs relative path (see Path Rules above) |
