@nebula-agents/electron-mcp

Embedded MCP server for Electron apps. It runs inside your Electron main process, exposes the BrowserWindow surfaces you choose, and lets MCP clients drive those renderers through Chrome DevTools Protocol.

Embedded vs External Attach

This package is for apps that want MCP automation as an opt-in feature of the app itself. Your main process decides when the server starts, which windows are reachable, and which custom tools are registered.

External-attach servers connect to an already-running Electron app through a remote debugging port. That can be useful for local debugging, but it does not let the app own surface naming, gating, or app-specific tools. If you want that external model, this package is probably not the right fit.

Quickstart

import { app, BrowserWindow } from "electron";
import {
  createElectronMcpServer,
  recommendedGuards,
} from "@nebula-agents/electron-mcp";

let mainWindow: BrowserWindow | null = null;

const mcp = createElectronMcpServer({
  getSurfaces: () => ({ main: mainWindow }),
});

app.whenReady().then(async () => {
  mainWindow = new BrowserWindow();

  if (recommendedGuards({ app, envVar: "MY_APP_MCP" })) {
    await mcp.start();
    console.log(`MCP listening at ${mcp.url}`);
  }
});

app.on("before-quit", () => {
  void mcp.stop();
});

Connect an MCP client to the logged HTTP URL. The default is http://127.0.0.1:9229/mcp.

API

const mcp = createElectronMcpServer({
  getSurfaces: () => ({ main: mainWindow, settings: settingsWindow }),
  port: 9229,
  host: "127.0.0.1",
  path: "/mcp",
  instructions: "Optional client-facing instructions.",
});

createElectronMcpServer(config) returns a synchronous handle:

• addTool(toolDef) registers a custom tool. Call it before start().
• start() starts the loopback HTTP server.
• stop() stops the HTTP server and detaches CDP sessions.
• isRunning reports whether the server is active.
• url is the bound MCP endpoint once running.

Bundled tools:

• list_surfaces
• show_surface
• hide_surface
• focus_surface
• reload_surface
• screenshot
• evaluate
• click
• type_text
• press_key
• hover
• query_dom
• ax_snapshot
• fill_form
• wait_for_load

Public types are available from the root export and from @nebula-agents/electron-mcp/types.

Custom Tools

import { z } from "zod";
import type { ToolDef } from "@nebula-agents/electron-mcp/types";

const resetStateTool: ToolDef = {
  name: "reset_state",
  config: {
    title: "Reset State",
    description: "Reset the app's local demo state.",
    inputSchema: { profile: z.enum(["empty", "demo"]) },
  },
  handler: async ({ profile }) => {
    await resetLocalState(profile);
    return { content: [{ type: "text", text: "ok" }] };
  },
};

mcp.addTool(resetStateTool);

Tools must be registered before start(). Dynamic tool registration and tools/list_changed are intentionally out of scope for 0.x.

Security Model

The server binds to loopback only by default: 127.0.0.1. Attempts to bind a non-loopback host throw. There is no authentication layer in 0.1.0; if your threat model requires more than loopback isolation, wrap this package in your own gate or do not start it.

Recommended production guard:

import { recommendedGuards } from "@nebula-agents/electron-mcp";

if (recommendedGuards({ app, envVar: "MY_APP_MCP" })) {
  await mcp.start();
}

The helper returns true only when the app is not packaged and the selected environment variable is set to "1". It throws if neither app.isPackaged nor isPackaged is provided.

Maintenance

This is open code with no support SLA. Agent Labs reviews issues and PRs on a best-effort basis. 0.x versions may change API shape based on real usage.

License

MIT.