ie-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| IE_PYDEPS | No | Extra sys.path directory for vendored selenium. | |
| IE_CAPTURE | No | Network capture through the recording proxy. 0/false/no/off turns the proxy off. | 1 |
| IE_NO_LOCK | No | Development escape hatch that disables the per-session lease. | |
| IE_LOG_FILE | No | Optional override for this session's log file. | <session-dir>\ie-mcp.log |
| IE_EDGE_PATH | No | Path to msedge.exe. | C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe |
| IE_LOCK_FILE | No | Optional override for this session's atomic lease file. | <session-dir>\session.lock |
| IE_SITE_LIST | No | Path to an Edge IE-mode site-list XML. If set, the server verifies the HKCU Edge policy points at it so listed sites render in IE mode. | |
| IE_CLICK_MODE | No | Default mode for ie_click: driver or async. | driver |
| IE_INSTRUMENT | No | Page instrumentation. 0/false/no/off turns it all off. | 1 |
| IE_SESSION_ID | No | Stable agent/session name. Different IDs can run concurrently; the same ID is exclusive. | pid-<MCP process PID> |
| IE_UPLOAD_DIR | No | Directory ie_upload may read from. Unset: uploads are disabled. | |
| IE_DEFAULT_URL | No | URL ie_open uses when none is given. | about:blank |
| IE_DRIVER_PATH | No | Path to IEDriverServer.exe. Unset: use the highest version under the per-user selenium cache. | |
| IE_CONSOLE_STUB | No | 1/true/yes creates a complete no-op console where a page has none, so its console calls are recorded. | 0 |
| IE_PAGE_TIMEOUT | No | Per-page load timeout in seconds. | 30 |
| IE_SESSION_ROOT | No | Root for session directories containing logs, leases and ownership records. | %TEMP%\ie-mcp\sessions |
| IE_TOOL_TIMEOUT | No | Seconds one tool call may take before the server answers BLOCKED. | 45 |
| IE_CAPTURE_JSONL | No | 1/true/yes also appends every captured exchange, after redaction, to a JSONL file. | 0 |
| IE_CLEAN_SESSION | No | 1/true/yes makes IEDriver clear the whole IE-mode cookie store and cache of the current user when the session starts and ends. | 0 |
| IE_ATTACH_RETRIES | No | IEDriver attach attempts. | 3 |
| IE_CAPTURE_BYPASS | No | Comma-separated host patterns kept off the capture proxy. | |
| IE_CAPTURE_REDACT | No | Redaction of secrets in the server log, captured traffic and console records. On unless set to 0/false/no/off. | 1 |
| IE_KEEP_ARTIFACTS | No | 1/true/yes keeps the JSONL capture file when the server exits. | 0 |
| IE_CAPTURE_MAX_BODY | No | Bytes kept of each captured request or response body. | 262144 |
| IE_CAPTURE_NO_CACHE | No | 1/true/yes strips conditional request headers so cache revalidations become full fetches the proxy can see. | 0 |
| IE_INTERACTION_MODE | No | Input strategy: background sends native input as window messages without taking focus; native requires window focus and is the compatibility fallback. | background |
| IE_CAPTURE_REDACT_FIELDS | No | Extra field names to redact, comma-separated, added to the built-in list. | |
| IE_CAPTURE_REDACT_HEADERS | No | Extra header names to redact, comma-separated, added to the built-in list. | |
| IE_CAPTURE_UPSTREAM_PROXY | No | host:port or http://host:port of a proxy the capture proxy forwards to. Unset: direct. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
IE interaction mode is selected when this MCP process starts. IE_INTERACTION_MODE=background is the default and suits automation on a user's active desktop: input is native (window messages) but does not take browser focus or move the user's mouse. Prefer it for navigation, reading, form entry, and ordinary clicks. If a legacy control, hover, upload, modal, or ActiveX interaction fails in background mode, restart this MCP with IE_INTERACTION_MODE=native as the compatibility fallback; native mode takes window focus and can mix with the user's own keystrokes and mouse. IE mode is never headless: a visible Edge window is always opened. ie_open needs an http(s) URL.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| ie_openA | Start (or reuse) an Edge IE-mode session and navigate to a URL (default IE_DEFAULT_URL). Keeps the session alive for later calls. An http(s) URL is required in IE mode: about:blank renders in Chromium and IEDriver cannot find an IE window, so a new session opened on it fails. |
| ie_gotoC | Navigate the current IE-mode session to a new URL. |
| ie_backC | Navigate back in browser history. |
| ie_forwardC | Navigate forward in browser history. |
| ie_resizeB | Resize the browser window (useful for consistent screenshots). |
| ie_closeA | Close the IE-mode session and quit the browser. The session name stays reserved for this server; ie_open starts a new browser. With force=true, running waits are cancelled and this session's own IEDriver and Edge are killed (only if they are still the recorded processes) without calling the driver at all: use it when a call hangs or the page is stuck in a dialog. |
| ie_windowsA | List the windows of the session as JSON: hwnd, kind (main | popup | html_dialog | script_dialog | system_dialog), class, title, url, owner_hwnd, visible, is_prompt and target ("hwnd:", for the target argument of the other tools). When no modal dialog is open and the browser is free it also gives each page window's driver_handle (for ie_switch_window) and which one is current. Never waits for a busy browser and works while a dialog is open. A system dialog is listed so you can tell the user: it is never answered by these tools. |
| ie_switch_windowA | Make a driver window the one the other tools act on (a pop-up from window.open, or a showModalDialog window). Give exactly one of: handle (a driver_handle from ie_windows), title_contains (case-insensitive part of the window's document title) or main=true (the session's first window). Returns the new window's title and URL. Switch back with main=true when you are done: after a window closes the driver has no current window. Alternative that needs no switching: pass target="hwnd:" to the other tools. |
| ie_close_windowA | Close a pop-up or modal dialog window: target is hwnd: (from ie_windows) or a driver_handle. It will not close the main window (use ie_close) or an attached tab (use ie_detach), and it never touches a system dialog (file, print or security prompt): those are reported as 'system dialog: ask the user'. A script alert/confirm/prompt is closed like its Cancel/OK button (a prompt then returns null). An hwnd target is closed with window.close() over COM, else with WM_CLOSE. |
| ie_textC | Get visible text of the page or of a specific frame. |
| ie_htmlA | Get the HTML source of the page or of a specific frame. Over COM (target hwnd:/tab:) it is the document's outerHTML (no doctype, markup as the engine normalised it), not the original source the driver returns. |
| ie_getC | Read an element's text (default), its 'value', or a named attribute/property. Set attr=text|value|. |
| ie_framesA | List the frames/iframes of the current page (index, name, id, src). Use the index or name with the 'frame' arg of other tools. |
| ie_gridB | Extract a tabular grid as structured rows. Auto-picks the table with the most multi-cell rows (or pass table_id). Returns headers + rows (header-keyed dicts when the header row is detected/given). App-agnostic. |
| ie_screenshotA | Capture PNG screenshots. scope=page (default) is the driver's view of the page; scope=element (by/value, the default when value is given) one element; scope=window renders the session's windows as the user sees them with PrintWindow: first the main window (or the attached tab's browser window), then every open modal HTML dialog and script alert/confirm/prompt, bottom-most to top-most, one image each, plus a text item that lists them (a system dialog is listed, never captured; a minimized window is reported, not restored). Window shots need no driver, so they work while a dialog blocks the page; target=hwnd: (from ie_windows) captures that one window of this session only. A window IE paints itself can come out blank: say so rather than guess. save_path, a bare file name, also saves it in the session's screenshots folder (several images: name, name-2, name-3, ...); saved files are kept after ie_close. |
| ie_wait_textA | Poll until a specific substring appears in the page text (for slow async content). Scans all frames unless 'frame' is given; returns which frame matched + a preview. For 'is the page loaded?' use ie_wait_ready instead. |
| ie_wait_readyA | Wait until the page finishes loading: every same-origin frame's document.readyState is 'complete' AND the DOM stops changing for a few polls (content settled). Handles slow async/frameset content. Use THIS to know content is ready, then search the data separately. Do NOT wait for a specific value to detect load — if it's absent you can't tell 'still loading' from 'not present'. Returns loaded=true/false with frame count, text length, element count and a content sample. |
| ie_wait_elementB | Wait for an element (by/value) to appear — or, with gone=true, to disappear. Use before acting on slow-rendering content. |
| ie_clickA | Click an element (auto-waits). 'by' is id/css/xpath/name/link_text/tag/class. action: click (default) | double | right. mode: driver (a WebDriver click; the default unless IE_CLICK_MODE=async) | async. An async click is queued on the page's own timer, so the call does not wait for the click's handlers (only the usual 'wait' pause follows) and cannot block even if the click opens a dialog that would block a driver click. It is script-initiated: there is no mousedown/mouseup/focus, handlers that test for a user gesture can behave differently, and the pop-up blocker may block a window.open it triggers. double and right always use the driver. Over COM (target hwnd:/tab:) a click is always queued on the page's timer and synthetic (script events, not mouse input). |
| ie_fillB | Type text into an input/textarea element (auto-waits). Over COM (target hwnd:/tab:) the value is set by script and key/change/blur events are fired: synthetic, not keystrokes. |
| ie_selectB | Select an in a dropdown, by label (visible text), option_value, or index. Provide exactly one of label/option_value/index. |
| ie_press_keyA | Press a key on an element (if by/value given) or the active element. Key names: Enter, Tab, Escape, Space, Backspace, Delete, Up/Down/Left/Right, Home, End, PageUp, PageDown, F5, or a literal character. Over COM (target hwnd:/tab:) the key is posted to the window as WM_KEYDOWN/WM_KEYUP (documentMode 7+), so Shift-modified characters are typed unshifted. |
| ie_hoverB | Hover the mouse over an element (for menus/tooltips). Over COM (target hwnd:/tab:) mouseover and mouseenter events are fired by script: synthetic, the mouse does not move. |
| ie_scrollB | Scroll: bring an element into view (by/value), scroll page/container to top|bottom (to=...), or by pixels (dx/dy). Needed for virtualized grids. |
| ie_uploadB | Set a file by sending a local file path. Only files inside the directory configured with IE_UPLOAD_DIR can be uploaded (disabled when it is unset). |
| ie_jsA | Execute JavaScript in the page or a frame and return the result. Over COM (target hwnd:/tab:) the script runs as a function body in the frame's own window: write ES3 (no JSON, let, arrow functions), return a primitive or an array (arrays come back joined with the character U+001E); a script error is reported, never sent to the page's onerror. |
| ie_consoleA | Records the server's page instrumentation made: script errors (kind error), alert/confirm/prompt (dialog-open when it opens, dialog when it closed, with the result), showModalDialog calls (modal: URL, features, dialogArguments, return value), window.open (open), console output (console, only where the page has a console, or all of it with IE_CONSOLE_STUB=1) and native XHR on https pages (xhr). Returns JSON {records, next_since_id}; pass next_since_id as since_id to read only what is new. Optional kinds (a list) and limit (default 100). Records are collected after each tool call, and only from pages the server has instrumented: load-time errors of the first page are not captured, and a dialog that closes between two calls leaves no record. The text is redacted. IE_INSTRUMENT=0 turns all of this off. |
| ie_console_clearA | Forget every record ie_console holds (ids keep counting). |
| ie_dialogA | Handle a script dialog (alert/confirm/prompt). action: accept (default) | dismiss | text | sendkeys (with text, for a prompt; it also accepts). Without target it uses the driver's alert, then a script alert or confirm window of the session. With target="hwnd:" (a script_dialog from ie_windows or a NOTICE) it needs no driver: it presses that window's button (alert: OK; confirm: accept = OK/true, dismiss = Cancel/false) after checking that it really is the session's own alert or confirm; a confirm's message is not readable through its window, so action=text then asks the driver alert when it can. A dialog shown as a TaskDialog (IE's "leave this page?" prompt has that shape) is accepted, with or without target, only when the page's instrumentation recorded it (a pending dialog-open record, see ie_console); otherwise accept is refused: ask the user. Answers carry that record as evidence. A prompt is answered only through the driver alert, so a prompt raised inside a showModalDialog window cannot be answered (ask the user). System dialogs (file, print, security prompts) are never answered: 'system dialog: ask the user'. |
| ie_networkA | List the HTTP requests the browser made, captured by the local recording proxy (and the XHR calls the page instrumentation saw, source page): one line per request, 'id source method status duration_ms size url', oldest first. Filter with url_contains, method and status; pass the last id seen as since_id to page (limit, default 50). Ie_request shows one entry's headers and bodies. HTTPS shows only the tunnel (host, timing). The initial URL of a session and responses served from the browser cache are not seen. Needs no browser call: it works while the page is busy or blocked. IE_CAPTURE=0 turns the proxy off. |
| ie_requestA | Show one captured request (id from ie_network): method, URL, status, timing, request and response headers and bodies. Bodies are decoded with the charset from Content-Type, then the charset of the document that made the request, then cp1252; a form body is percent-decoded the same way; gzip/deflate responses are decoded from a copy; binary bodies are summarised as . body_limit (default 20000) caps the characters shown per body. Secrets are redacted. An HTTPS entry is only a tunnel (host, timing). |
| ie_network_clearA | Forget every captured request ie_network holds (ids keep counting). |
| ie_tabsA | List the IE-mode tabs the user has open in Edge windows, as JSON: hwnd (give it to ie_attach), target ("tab:"), top_hwnd, pid, title, url and attached. Only the visible tab of each window is listed (activate the tab in the browser first). Windows of other ie-mcp sessions are never listed. |
| ie_attachA | Attach to one of the user's IE-mode tabs (hwnd from ie_tabs) so the read and interact tools (ie_text, ie_html, ie_click, ie_fill, ie_js, ie_wait_text, ie_wait_element, ie_windows, ie_console, ie_screenshot scope=window ...) act on it without a target, over COM. The user keeps their login and page state. The tab's script instrumentation (see ie_console) is installed and stays in the tab until it is reloaded, even after ie_detach. ie_close needs ie_detach first (or force=true). Limits: no driver-only tools while attached (navigation, history, ie_wait_ready, page screenshot, upload: call ie_detach first), no proxy capture of the tab's traffic (only what the page's own instrumentation records), and a page's prompt cannot be answered (only alert and confirm windows pass the ie_dialog checks; answer a prompt yourself or ask the user). Keys, hover, window screenshots and ie_console work through COM and Win32. |
| ie_detachA | Detach from the attached tab: the tools go back to the IE driver session. The page's instrumentation stays in the tab until it is reloaded. |
| ie_statusA | Session state as JSON: active/alive, title, url, window_handles, and the interaction mode, session identity/directory, owned browser PIDs/profile, the page modifications: instrumented (wrappers installed), console_stub, xhr_wrapped, and the network capture: capture (proxy, page-only, off, unverified), capture_note (what it does not show), capture_internal_errors (proxy bugs, if any) and modifications (every active change the harness makes to pages, requests and input, each with its off switch). Never waits for a busy browser: while another call holds it, title/url/window_handles are left out and "driver": "busy" is reported. |
| ie_browsersA | List ALL Edge IE-mode windows and IEDriver processes open on the machine, flagging which one THIS session owns (mine=true) and which are orphans. Use to see leftover browsers from prior/other runs. |
| ie_kill_orphansA | Terminate only IE-mode Edge / IEDriver processes recorded for crashed ie-mcp sessions. Never kills browsers owned by live agents or unknown processes. |
| ie_sleepA | Sleep for N seconds (last resort; prefer ie_wait_ready / ie_wait_text). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 39 tools
Most tools target a clearly distinct resource or action, and the long descriptions carefully separate the near-neighbours (driver windows via ie_switch_window/ie_windows vs. the user's tabs via ie_tabs/ie_attach, ie_close vs. ie_close_window vs. ie_detach vs. ie_kill_orphans). The wait family (ie_wait_ready/ie_wait_text/ie_wait_element/ie_sleep) and the two clear tools overlap slightly, but each has an explicit 'when to use me instead' note, so an agent can still choose correctly.
Nearly all 39 names are ie_-prefixed snake_case with a verb_noun shape (ie_open, ie_goto, ie_click, ie_wait_text, ie_close_window). The only deviations are the two noun_verb exceptions ie_console_clear and ie_network_clear, plus a few bare-verb names (ie_back, ie_forward, ie_close) where the resource is implicit. Overall predictable and readable.
39 tools is heavy for one server, though the domain is genuinely broad (navigation, DOM reading, input, dialogs, network capture, window/tab lifecycle, process cleanup). A few entries feel marginal or bookkeeping-only (ie_sleep, ie_console_clear, ie_network_clear, ie_resize) and could be folded into other tools or arguments. It is over-scoped rather than unjustified.
The surface covers the full automation lifecycle: session open/close, navigation and history, page/frame reads, grid extraction, clicking/filling/selecting/keys/hover/scroll/upload, script dialogs, screenshots, console and network evidence, plus attach/detach and orphan cleanup. Remaining gaps are minor and workaroundable via ie_js: no multi-element query tool (returning all matches for a selector), no cookie/session or download handling, and no dialog handling for prompts inside modal dialogs.