By 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. SupportsfileMaskfilter.search_text/search_regex/search_file/search_symbol— Returns structured results with exact coordinates (line, column, byte offsets). Supportspathsglob filters and!excludes. Use this when you need precise locations for further operations.search_symbolis 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 withget_file_problemsafter 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) |