Skill: IntelliJ IDEA MCP Integration

Control and interact with JetBrains IntelliJ IDEA directly through the Model Context Protocol (MCP) server.

Trigger

• /idea - Show available IntelliJ IDEA MCP commands and current IDE status
• /idea [action] - Execute a specific IDE action

Arguments

$ARGUMENTS

Prerequisites

The JetBrains MCP server must be configured and running:

1. IntelliJ IDEA must be open with the MCP Server plugin enabled
2. MCP Server must be added to Docker MCP Gateway:

   mcp-find jetbrains
   mcp-config-set jetbrains {"port": <PORT>}
   mcp-add jetbrains
   

3. The port can be found in C:\Users\Chris\AppData\Roaming\Claude\claude_desktop_config.json under IJ_MCP_SERVER_PORT

Available Tools

File Operations

Editor Operations

Project & VCS

Run & Debug

Terminal & IDE Actions

Utility

Scopes & File Colors

IntelliJ IDEA scopes provide powerful file filtering and visual organization capabilities.

Scope Configuration

Scopes are stored in .idea/scopes/*.xml with the following format:

<?xml version="1.0" encoding="UTF-8"?>
<component name="DependencyValidationManager">
  <scope name="Scope Name" pattern="file[ModuleName]:path//*" />
</component>

Scope Pattern Syntax

File Colors Configuration

File colors are configured in .idea/workspace.xml under <component name="FileColors">:

<component name="FileColors">
  <fileColor scope="Scope Name" color="hexcode" />
</component>

Dark Theme Color Palette:

If $ARGUMENTS is "scopes":

1. List existing scopes from .idea/scopes/
2. Show current file colors from .idea/workspace.xml
3. Suggest scope improvements based on project structure

If $ARGUMENTS is "scopes setup" or "scopes create":

1. Analyze project structure (folder hierarchy)
2. Create logical scope groupings
3. Generate scope XML files in .idea/scopes/
4. Configure file colors in workspace.xml
5. Use dark theme colors by default

If $ARGUMENTS is "scopes colors":

1. Read current file colors from workspace.xml
2. Display color assignments
3. Suggest adjustments for dark/light themes

Command Handling

If $ARGUMENTS is empty or "status":

1. Check if JetBrains MCP server is connected
2. If not connected, attempt to connect using mcp-find, mcp-config-set, and mcp-add
3. Show current IDE status:
   • Currently open file
   • All open files
   • Project VCS status
   • Running progress indicators

If $ARGUMENTS is "files":

List all open files in the editor using get_all_open_file_paths.

If $ARGUMENTS is "tree" or "structure":

Show project directory tree using list_directory_tree_in_folder with path "/" and maxDepth 3.

If $ARGUMENTS is "vcs" or "git":

Show VCS status using get_project_vcs_status.

If $ARGUMENTS is "runs" or "configurations":

List run configurations using get_run_configurations.

If $ARGUMENTS is "breakpoints":

List all breakpoints using get_debugger_breakpoints.

If $ARGUMENTS is "modules":

List project modules using get_project_modules.

If $ARGUMENTS is "deps" or "dependencies":

List project dependencies using get_project_dependencies.

If $ARGUMENTS is "terminal":

Get terminal output using get_terminal_text.

If $ARGUMENTS is "actions":

List available IDE actions using list_available_actions.

If $ARGUMENTS starts with "open ":

Open the specified file using open_file_in_editor.

If $ARGUMENTS starts with "run ":

Execute the specified run configuration using run_configuration.

If $ARGUMENTS starts with "search ":

Search in files using search_in_files_content with the query.

If $ARGUMENTS starts with "find ":

Find files by name using find_files_by_name_substring.

If $ARGUMENTS starts with "exec " or "action ":

Execute IDE action by ID using execute_action_by_id.

If $ARGUMENTS starts with "cmd " or "terminal ":

Execute terminal command using execute_terminal_command.

If $ARGUMENTS is "current" or "active":

Show the currently active file path and content using get_open_in_editor_file_path and get_open_in_editor_file_text.

If $ARGUMENTS is "selected" or "selection":

Get selected text using get_selected_in_editor_text.

If $ARGUMENTS is "help":

Display this skill documentation with all available commands.

Usage Guidelines

1. Always ensure IntelliJ IDEA is running before attempting to use these commands
2. File paths are relative to project root unless specified as absolute
3. Use get_project_vcs_status before making changes to understand current state
4. Prefer replace_specific_text over replace_file_text_by_path for targeted edits
5. Check get_progress_indicators if IDE seems busy or unresponsive
6. Use wait when chaining commands that need IDE to process (e.g., after running a configuration)

Example Usage

/idea                    # Show IDE status and open files
/idea files              # List all open files
/idea tree               # Show project structure
/idea vcs                # Show Git status
/idea open src/main.ts   # Open a specific file
/idea run "Debug App"    # Run a configuration
/idea search TODO        # Search for TODO in all files
/idea find config        # Find files with "config" in name
/idea terminal npm test  # Run npm test in terminal
/idea current            # Show current file content
/idea help               # Show this help

Error Handling

If the MCP server is not connected:

1. Use mcp__MCP_DOCKER__mcp-find with query "jetbrains" to verify availability
2. Use mcp__MCP_DOCKER__mcp-config-set to set the port configuration
3. Use mcp__MCP_DOCKER__mcp-add to activate the server

Common issues:

• Port mismatch: Check IJ_MCP_SERVER_PORT in claude_desktop_config.json
• IDE not running: Start IntelliJ IDEA and ensure MCP Server plugin is enabled
• Plugin disabled: Go to Settings > Plugins > MCP Server and enable it

References

• Scopes Guide - Complete guide to IDEA scopes and file colors

Metadata

author: Christian Kusmanow / Claude
version: 1.0.0
last_updated: 2026-01-31
migrated_from: .claude/skills/idea v2.0.0
change_surface: references/ (scopes guide, tool updates)