Eclipse MCP Server
Turns a running Eclipse IDE into an MCP server, so that external LLM clients (Claude Code, Cursor, any MCP-capable agent) can ask the IDE for what they cannot cheaply reconstruct from files: the resolved Java model, the builder's problem markers, the debugger and the live workbench.
Built and maintained by vogella GmbH, and used in our consulting and in our AI based Java cleanup services for legacy code and code optimization.
The server is disabled by default, listens on 127.0.0.1 only and rejects every request without the bearer token.
Most tools are read-only; every tool that changes something says so in its own description, and those that can default to a dry run do.
Installing
In Eclipse, choose Help > Install New Software, add
https://vogellacompany.github.io/eclipse-mcp-server/
and install the Eclipse MCP Server feature.
The site carries the newest build only; older versions are available as the repository zip attached to each GitHub release, through Add > Archive.
Building
Requires JDK 25 and Maven 3.9 or newer.
mvn clean verify
The p2 repository ends up in update-site/com.vogella.eclipse.mcp.repository/target/repository.
To work on the code in Eclipse, import the projects with Search for nested projects enabled and set target-platform/com.vogella.eclipse.mcp.target/com.vogella.eclipse.mcp.target.target as the active target platform.
Every push to main publishes to the update site; pushing a v<version> tag additionally creates a GitHub release with the repository zip.
Enabling the server
Preferences > General > MCP Server:
- Enable MCP server, off by default
- Port,
8642 by default
- Tool call timeout,
30 seconds by default
- UI thread wait,
25 seconds by default: how long a tool waits for a busy UI thread before it withdraws the request, capped by the tool call timeout
Changes apply immediately.
The page also shows the URL, the bearer token and the discovery file, and can regenerate the token.
If the port is taken, the server stays down and the page says why; it never moves to another port behind a client's back.
In an RCP application
The server starts through a declarative service, so an RCP application needs org.apache.felix.scr and a workspace, but no org.eclipse.ui.startup.
Install com.vogella.eclipse.mcp.core, com.vogella.eclipse.mcp.basic, com.vogella.eclipse.mcp.server and the third party bundles the feature lists; specialized provider bundles are optional and each adds its own tools.
com.vogella.eclipse.mcp.ui also resolves in a pure E4 application that ships the org.eclipse.ui bundles it requires, which then gets the widget, screenshot, keyboard, dialog and settle tools, with parts named by their model element id; the tools built on editors, views, perspectives and workbench commands need the 3.x workbench and say so.
Without the ui bundle there is no preference page, so enable the server in plugin_customization.ini:
com.vogella.eclipse.mcp.server/enabled=true
com.vogella.eclipse.mcp.server/port=8642
The product only reads plugin_customization.ini when it points at it, with the preferenceCustomization product property or -pluginCustomization <file> on the command line.
The server bundle's built manifest requires the osgi.component extender, so without org.apache.felix.scr in the product it does not resolve.
A product materialized by Tycho does not start bundles on its own, so start org.apache.felix.scr (org.apache.felix.scr@2:start in config.ini) for the server, and org.eclipse.core.runtime@start and org.eclipse.equinox.common@2:start for the application itself, in the .product configuration or as osgi.bundles entries; an application whose runtime bundles are not started fails with "Unable to acquire application service".
The ui bundle is optional: core, basic and server run the server with the workspace, file, build and log tools but no UI tools.
Adding com.vogella.eclipse.mcp.ui requires the 3.x workbench and the other bundles listed in its META-INF/MANIFEST.MF, but not org.eclipse.ui.ide, org.eclipse.compare or org.eclipse.debug.ui, so it adds no p2, navigator or Debug perspective to a product; leave it out unless you want the screenshot, widget and keyboard tools, or in an IDE the editor and view tools.
com.vogella.eclipse.mcp.ide holds the IDE-only tools, eclipse_open, eclipse_open_compare, eclipse_run_launch_shortcut and eclipse_import_project; leave it out of an RCP product.
Connecting a client
The server writes a discovery file:
<workspace>/.metadata/.plugins/com.vogella.eclipse.mcp.server/endpoint.json
{
"state": "listening",
"url": "http://127.0.0.1:8642/mcp",
"token": "0f0f2a2e-1f9c-4c4a-9a0e-6d0f8f0f1e2b",
"workspace": "/home/me/workspace/swt",
"startedAt": 1787300000000
}
For Claude Code:
claude mcp add --transport http eclipse http://127.0.0.1:8642/mcp \
--header "Authorization: Bearer $(jq -r .token <workspace>/.metadata/.plugins/com.vogella.eclipse.mcp.server/endpoint.json)"
The transport is Streamable HTTP and every request carries Authorization: Bearer <token>; anything else gets a 401.
The token lives in ~/.eclipse/com.vogella.eclipse.mcp.server/token with owner-only permissions, and survives restarts, updates and workspace switches, so a client is configured once.
With two IDEs open, the first one owns the port; workspace in the discovery file tells which one a client reached.
After eclipse_restart, compare startedAt to know the new server is up; some clients need a manual reconnect, in Claude Code through /mcp.
Several clients can share one server.
While more than one is connected, eclipse_get_build_status, eclipse_get_test_results, eclipse_stop_sampling and eclipse_get_provisioning_status refuse to guess "the most recent" entry, so pass the id explicitly.
The server offers tools only: initialize, ping, tools/list and tools/call.
Every tool returns pretty-printed JSON, and every list-returning tool honours maxResults and reports total and truncated.
Scripting the IDE from outside
eclipse_run_script runs a sequence of tools with assertions in one call, and two scripts in releng make that runnable from a build:
# against the IDE you are working in
releng/mcp-script.py releng/scripts/content-assist.json
# against a throwaway IDE, on a workspace and a port of its own
releng/mcp-test-ide.sh --ide /path/to/eclipse --junit results.xml releng/scripts/smoke.json
mcp-script.py prints each step, exits non-zero on a failed expectation and can write JUnit XML.
mcp-test-ide.sh starts the IDE on a fresh workspace and configuration area, sharing the installation's plug-ins but not any bundle substituted into it, runs the scripts and shuts the IDE down again.
Testing Eclipse and SWT changes
The UI tools address widgets by their place in the SWT hierarchy rather than by screen coordinates, so a check survives a resize, a theme and another machine:
eclipse_list_ui_targets names the shells and parts; eclipse_get_widget_tree lists the widgets under one with a path for each, bounds in three coordinate systems, CSS id and class, and with includeMetrics what the control computes for itself: preferred size, trim, font and item height.eclipse_press_widget, eclipse_set_widget_text, eclipse_select_tab, eclipse_expand_row, eclipse_click, eclipse_drag, eclipse_scroll, eclipse_press_key and eclipse_type_text act on a path; key and click fall back to SWT events where the window system refuses synthetic input.eclipse_wait_for waits for a shell, widget, selection, editor or job condition, and eclipse_wait_until_settled for the display queue, the jobs and the reconcilers.eclipse_screenshot captures a part, a shell or the display; settle and settlePixels make a capture repeatable, and method: print paints the widgets instead of reading the screen.eclipse_mark_log and then eclipse_get_log_entries show what an action logged, UI freezes included.
To run modified SWT or platform code, import the bundle's project into the IDE's workspace, build it, run eclipse_substitute_bundle with action: substitute and then eclipse_restart; action: restore and another restart put the installed bundle back.
For SWT, import the fragment for your platform, such as binaries/org.eclipse.swt.gtk.linux.x86_64, from a checkout whose native libraries match the Java code: a checkout without Git LFS has pointer files in their place, which the substitution refuses.
eclipse_hot_code_replace redefines changed classes without a restart where the change allows it.
eclipse-harness builds on this: it starts a throwaway IDE, runs eclipse_run_script scenarios and compares the captures pixel by pixel with baselines.
Tools
Tools marked ✎ change something; the rest are read-only.
Workspace and files
| Tool | Purpose |
|---|
eclipse_list_projects | Projects with natures and open state |
eclipse_resolve_path | Maps project names, workspace paths and absolute paths to each other and to the git repository |
eclipse_read_file, eclipse_search_text, eclipse_find_resources | Read files, search their text, find files by name in workspace, target platform and installation |
eclipse_read_image | Return a PNG, JPEG, GIF or WebP from a project as an image the model can see |
✎ eclipse_write_file, eclipse_edit_file | Write a file or replace a passage, keeping the old content in local history |
eclipse_get_local_history, ✎ eclipse_restore_local_history | List, read and restore the versions Eclipse keeps of a file, including a deleted one |
✎ eclipse_delete | Delete a source file, reporting registry and manifest entries that would dangle |
✎ eclipse_refresh, eclipse_save_workspace | Pick up external changes, save the workspace |
✎ eclipse_set_project_state, eclipse_import_project, eclipse_remove_project | Open, close, import and remove projects |
eclipse_get_project_dependencies, eclipse_get_classpath | Project references and the resolved build path |
Problems, builds and logs
| Tool | Purpose |
|---|
eclipse_get_problems, eclipse_mark_problems | Compiler errors and warnings, and a baseline to compare against |
✎ eclipse_build, eclipse_cancel_build, eclipse_get_build_status | Run builders as a job and poll the result |
eclipse_wait_until_quiet, eclipse_pause | Wait for builds and refreshes, or for a fixed time |
eclipse_get_log_entries, eclipse_mark_log | Read the Error Log, optionally from a marker |
✎ eclipse_clear_log, eclipse_log_status | Empty the Error Log, write an entry into it |
eclipse_get_preferences, ✎ eclipse_set_preference | Read and write preferences, with the scope each value comes from |
✎ eclipse_run_command, eclipse_get_command_output | Run a shell command in a named directory and poll its output |
Java
| Tool | Purpose |
|---|
eclipse_find_references | References to a type or member, single or batched as counts |
eclipse_list_declarations | Declarations cross-checked against the extension registry and e4 models, for dead code sweeps |
eclipse_get_call_hierarchy, eclipse_get_type_hierarchy | Callers, supertypes and subtypes |
eclipse_get_source, eclipse_search_types | Source and Javadoc of any type on the classpath, type search by name |
✎ eclipse_rename | Rename through the JDT refactoring |
✎ eclipse_clean_up, eclipse_remove_unused_imports, eclipse_organize_imports, eclipse_format | JDT clean-ups, import handling and formatting |
✎ eclipse_set_java_version | Set a project's compiler level and JDK |
✎ eclipse_run_tests, eclipse_get_test_results | Run JUnit tests with optional VM arguments and read the results |
✎ eclipse_hot_code_replace | Redefine classes in the running IDE |
Plug-in development
| Tool | Purpose |
|---|
eclipse_get_bundle_info, eclipse_analyze_dependencies | Bundles as PDE resolved them, declared versus used dependencies |
✎ eclipse_edit_manifest, eclipse_set_bree | Edit manifest headers, set the execution environment |
eclipse_get_target_platform, ✎ eclipse_set_target_platform | Read and set the active target platform |
✎ eclipse_install_bundle, eclipse_substitute_bundle | Install a bundle into the live framework, or run a workspace bundle in place of the installed one |
Debugging and profiling
| Tool | Purpose |
|---|
eclipse_list_breakpoints, ✎ eclipse_set_breakpoint | Read and edit breakpoints |
eclipse_list_launch_configurations, ✎ eclipse_debug_launch | List and start launches |
eclipse_debug_status, eclipse_debug_get_frames | Sessions, threads, frames and variables |
✎ eclipse_debug_evaluate, eclipse_debug_control | Evaluate expressions, step, resume and terminate |
eclipse_start_sampling, eclipse_stop_sampling, eclipse_show_trace | Sample thread stacks to profile or diagnose a freeze, and render them as a flame graph |
eclipse_start_flight_recording, eclipse_stop_flight_recording | Record the IDE's JVM with Java Flight Recorder |
Git
| Tool | Purpose |
|---|
eclipse_get_git_status | Repository state through EGit |
✎ eclipse_add_git_repository, eclipse_checkout, eclipse_fetch_pull_request | Register a repository, switch branches, fetch a GitHub pull request |
✎ eclipse_revert_files | Revert files to HEAD, keeping the discarded content in local history |
Workbench and UI
| Tool | Purpose |
|---|
eclipse_get_editor_context, eclipse_list_editors, ✎ eclipse_close_editor | Active editor, cursor and selection, open editors |
✎ eclipse_open, eclipse_open_compare | Open a file or element, open a compare editor |
eclipse_get_selection, ✎ eclipse_set_selection | Read and set the selection |
✎ eclipse_type_text, eclipse_press_key, eclipse_set_widget_text, eclipse_press_widget, eclipse_set_sash, eclipse_click, eclipse_drag, eclipse_scroll, eclipse_double_click_text, eclipse_expand_row, eclipse_select_tab | Drive editors and widgets |
eclipse_get_text_bounds, eclipse_list_annotations, eclipse_get_context_menu | Text geometry, editor annotations, context menu contents |
eclipse_list_ui_targets, eclipse_get_widget_tree, eclipse_inspect_widget, eclipse_get_focus | Shells, parts and widgets, with bounds, computed sizes, CSS styling and keyboard focus |
✎ eclipse_dismiss_dialog | Answer an open dialog |
✎ eclipse_reset_dialog_settings | Forget the answers wizards and dialogs remembered |
eclipse_list_commands, ✎ eclipse_run_workbench_command | List and run workbench commands |
✎ eclipse_run_launch_shortcut | Invoke a Run As or Debug As shortcut on workspace resources (dry run by default), reporting the configurations it created and the launches it started |
✎ eclipse_select_menu_item | Pick a main menu or context menu entry by its labels, without a native menu appearing |
✎ eclipse_show_view, eclipse_hide_view, eclipse_move_part, eclipse_set_part_state | Arrange views |
eclipse_list_perspectives, ✎ eclipse_switch_perspective, |
Installation
| Tool | Purpose |
|---|
eclipse_get_installation | Product, installed features and revertable configurations |
✎ eclipse_add_repository, eclipse_remove_repository | Manage update sites |
eclipse_check_for_updates, ✎ eclipse_update, eclipse_install, eclipse_uninstall, eclipse_get_provisioning_status | Update, install and uninstall through p2 |
✎ eclipse_restart, eclipse_exit | Restart or shut down the IDE |
Contributing a tool
Tools are contributed through the com.vogella.eclipse.mcp.core.tools extension point:
<extension point="com.vogella.eclipse.mcp.core.tools">
<tool class="com.example.MyTool"/>
</extension>
com.example.MyTool implements com.vogella.eclipse.mcp.core.IMcpTool.
It is called on a worker thread, must not open a dialog, must say in its description if it changes anything, and must finish within the call timeout or hand back a handle to poll.
See AGENTS.md for the full set of rules.
Bundles
| Bundle | Contains |
|---|
com.vogella.eclipse.mcp.core | Provider-independent tool API, registry, extension point and shared infrastructure; no MCP, Jetty or UI dependency |
com.vogella.eclipse.mcp.basic | General-purpose workspace, file, build, preference, log, command and other basic tools; provider depending on core |
com.vogella.eclipse.mcp.server | MCP protocol, embedded Jetty, bearer token and discovery file |
com.vogella.eclipse.mcp.ui | Workbench tools, screenshots, widget inspection, preference page |
com.vogella.eclipse.mcp.jdt | Java model, refactoring, clean-up and test tools |
com.vogella.eclipse.mcp.debug | Breakpoint and debug session tools |
com.vogella.eclipse.mcp.pde | Plug-in development tools |
com.vogella.eclipse.mcp.git | EGit tools |
com.vogella.eclipse.mcp.ide | IDE-only tools: open in editor, compare, launch shortcuts, project import |
com.vogella.eclipse.mcp.p2 | Provisioning tools |
Commercial support
vogella GmbH offers training and consulting around Eclipse and its tooling, and AI based Java cleanup for legacy code and code optimization.
Issues and pull requests are welcome here; the commercial route exists for work that wants a schedule attached.
