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 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 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:

/.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 /.metadata/.plugins/com.vogella.eclipse.mcp.server/endpoint.json)"

The transport is Streamable HTTP and every request carries Authorization: Bearer ; 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.

Tools

Tools marked ✎ change something; the rest are read-only.

Workspace and files

Problems, builds and logs

Java

Plug-in development

Debugging and profiling

Git

Workbench and UI

Installation

Contributing a tool

Tools are contributed through the com.vogella.eclipse.mcp.core.tools extension point:

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

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.