Ghost MCP server
2026년 11월 2일 커밋Windows 및 Linux 환경의 agent를 위한 검증된 백그라운드 데스크톱 제어 기능을 제공하며, API가 없는 앱, 윈도우, 쉘, 브라우저의 자동화를 지원합니다.
다른 이름 NORTHTEKDevs/ghost
- 스타
- 28
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- 0.23.4
- 마지막 커밋
- 2026년 11월 2일
- 라이선스
- MIT
Ghost MCP란?
Ghost은(는) MCP server입니다. Windows 및 Linux 환경의 agent를 위한 검증된 백그라운드 데스크톱 제어 기능을 제공하며, API가 없는 앱, 윈도우, 쉘, 브라우저의 자동화를 지원합니다.
프로젝트 README에서 생성된 요약
Ghost MCP server 정보
Ghost는 Windows 및 Linux에서 실행되는 agent와 프로그램을 위한 검증된 백그라운드 데스크톱 제어 기능을 제공합니다. 이를 통해 개발자는 API가 없는 레거시 Win32, WPF, Electron, UWP 소프트웨어 및 웹 브라우저를 포함한 애플리케이션을 자동화할 수 있습니다. 마우스와 키보드를 점유하는 기존 도구와 달리, Ghost는 window message를 게시하거나 Win32 UI Automation 및 AT-SPI2와 같은 접근성 API를 사용하여 백그라운드에서 작동합니다. 이를 통해 사용자가 포커스 탈취 없이 다른 윈도우에서 작업을 계속하는 동안 agent가 클릭, 타이핑 및 탐색을 수행할 수 있습니다.
이 server는 Claude Code, Cursor, Codex와 같은 클라이언트를 위한 Model Context Protocol 인터페이스나 CLI 및 로컬 REST API를 통해 사용할 수 있습니다. 윈도우 관리, 쉘 실행, DevTools 포트를 통한 브라우저 자동화를 위한 특화된 도구를 포함합니다. 요소 탐색을 위해 운영 체제 자체의 접근성 레이어에 의존하므로, vision API 키 없이도 UI 구성 요소의 실제 이름과 역할을 제공합니다. 모든 작업 뒤에는 의도한 변경이 실제로 발생했는지 확인하는 검증 단계가 따릅니다.
활용 사례
- 1백그라운드 브라우저 자동화개발자는 자신의 작업을 방해받지 않고 AI에게 기존 브라우저 세션에서 탭을 탐색하거나 JavaScript를 실행하도록 지시할 수 있습니다.
- 2자동화된 워크플로 검증특정 UI 요소가 존재하는지 또는 작업 수행 후 값이 변경되었는지 확인하기 위해 이 server를 사용할 수 있습니다.
- 3터미널 명령 실행코딩 agent가 호스트 머신에서 빌드, git 작업 및 지속적인 쉘 상태를 직접 관리할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
구성
GHOST_VISION_API_KEY비밀Not needed for agents: the model driving Ghost reads ghost_see and ghost_screenshot itself. Only enables the optional built-in vision tier for description targets (any OpenAI-compatible vision endpoint).
GHOST_VISION_API_KEY비밀Not needed for agents: the model driving Ghost reads ghost_see and ghost_screenshot itself. Only enables the optional built-in vision tier for description targets (any OpenAI-compatible vision endpoint).
GHOST_FOCUS_LOCKGHOST_FOCUS_POLICY
| 이름 | 설명 | 유형 |
|---|---|---|
| GHOST_VISION_API_KEY | Not needed for agents: the model driving Ghost reads ghost_see and ghost_screenshot itself. Only enables the optional built-in vision tier for description targets (any OpenAI-compatible vision endpoint). | 비밀 |
| GHOST_VISION_API_KEY | Not needed for agents: the model driving Ghost reads ghost_see and ghost_screenshot itself. Only enables the optional built-in vision tier for description targets (any OpenAI-compatible vision endpoint). | 비밀 |
| GHOST_FOCUS_LOCK | — | |
| GHOST_FOCUS_POLICY | — |
자동 검사
2026년 11월 12일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
README
GitHub에서 보기Ghost
Verified control of the whole desktop, for agents and programs, on Windows and Linux. Ghost gives Claude Code, Codex, Cursor, any MCP harness, or a plain script the operating system's own control surface: the apps with no API, the windows, the shell, and the browser you are already logged into - in the background without taking your screen or cursor, with every action proven to have happened.
Like Playwright, but for the native desktop, and built for agents. Ghost does the perceiving, the acting, and the verifying; the model you are already running does any looking that is needed, so there is no vision API key to set.
One MCP surface, two engines: Win32 UI Automation on Windows, AT-SPI2 over D-Bus on Linux. The verbs, the locator tiers and the act-then-verify loop are written once and behave the same on both. Platform support · Linux setup
Why Ghost is different
- Runs in the background, and that is enforced. An agent can click, type, and
use shortcuts inside an app while you keep working in another window - no focus
steal, no cursor jump. It posts window messages to real controls and uses UI
Automation patterns on windowless ones; most tools can only drive whatever is in
the foreground. Since 0.19 this is a policy, not a preference: the focus policy
defaults to
background. Since 0.20 it is also constructive: anything Ghost starts (an app, a windowed browser) is born on a hidden desktop that has its own input queue and cannot take your foreground, and the ordinary verbs drive it there by window title. A call that truly has no background path fails naming the action instead of quietly taking the screen. Since 0.22 the policy is locked there: no tool call can raise it, so an agent cannot decide on its own to take your mouse. You can, by settingGHOST_FOCUS_LOCK=offin the server's environment. And since 0.23 a window that grabs the foreground on its own - browsers do, on their own accessibility calls - is handed straight back, so your typing keeps going where you are looking. Measured on a real desktop with a person typing throughout: of roughly 490 keystrokes a run, zero to one reached the window the agent was driving. (how) - Never your window by accident. The session remembers the last window the agent named or launched and every window-scoped verb targets it by default. The human's foreground window is used only when nothing was ever anchored, and the response says so. Three weeks of real transcripts showed "element not found in the foreground window" as the top failure before this; it was the agent searching the window you had open.
- Many agents at once. Requests are dispatched in parallel, so a 15-second wait in one tab does not stall an instant query behind it, and a second Ghost process runs its own browser alongside the first without contending for the mouse.
- Prove it on your machine.
ghost verifydrives the real MCP server over stdio and audits every claim above against hard timing budgets, exiting non-zero if any of them does not hold on your hardware. - Every action is verified. Ghost re-checks the screen (or reads the control's
value back) after acting and returns
verified/focus_confirmed- never a blindok:true. Agents fail by acting and not knowing if it worked; Ghost closes that loop. - Drives apps with no API. Legacy Win32, WPF, Electron, UWP, vendor portals - the software that has no integration and most needs automating. No CDP, no browser, no app cooperation required.
- No vision key. The model driving Ghost reads
ghost_see(every element with its name, role and on-screen centre) orghost_screenshotitself. Ghost's own vision tier is optional, exists for callers with no model of their own, and is off until configured. - Accessibility-native and deep. Real element discovery through the OS's own accessibility API - UI Automation on Windows, AT-SPI2 on Linux - not pixel-guessing. Elements come back with real names, roles and bounds.
See it in one script: examples/background_agent_demo.py
drives an app in the background while the foreground stays yours.
Honest comparison vs Playwright-MCP / cua-driver / Computer Use:
docs/comparison.md.
What people use it for
Vision is the smallest part of it. In a typical session an agent calls Ghost mostly to act, to manage windows and processes, to run commands, and to read state back.
| Use | Tools | Typical caller |
|---|---|---|
| Driving apps with no API: installers, legacy line-of-business software, vendor portals, WPF and Electron tools | ghost_act, ghost_key, ghost_scroll, ghost_drag |
agents, RPA scripts |
| Window and process control: launch invisibly, focus, minimize, restore, close, recover hidden windows, sweep orphaned browsers | ghost_window, ghost_desktop_*, ghost_stats |
agents, ops scripts |
| A terminal for the agent: builds, git, CLIs, persistent PowerShell state, spawning another Claude Code session | ghost_shell, ghost_run |
coding agents on Windows |
| Driving the browser you are already signed into, through its DevTools port: tabs, navigation, DOM clicks, JS eval, page text | 19 ghost_browser_* and ghost_tab_* tools |
agents, web automations |
| Reading data out of apps with no export: accessibility text, tab text, OCR | ghost_see mode=text, ghost_tab_text |
agents, reporting scripts |
| Making "did it work" a machine check: element exists, value equals, wait for idle or text | ghost_assert, ghost_wait |
QA agents, CI |
| Isolated desktops: overnight GUI work and parallel agents that never touch the human's screen | ghost_window op=launch, the focus policy, ghost_desktop_* |
autonomous runs |
| Reproducible multi-step flows with retries and conditions, no model in the loop | intents via ghost run, POST /run, ghost_execute_intent |
scheduled jobs |
| The clipboard as a bridge into apps that resist typing | ghost_clipboard |
all of the above |
Every row runs under the same guarantees: the action returns verified, the
default policy never takes your foreground, and Ctrl+Alt+G stops every Ghost
process at once.
What is Ghost?
Ghost is the layer between a model and the desktop. The model reasons; Ghost sees the screen the way the operating system does, acts on real controls without touching your foreground, and reports whether the action took. It gives programmatic control over any desktop application - native Win32, Electron, WPF, UWP, GTK, Qt, or otherwise - to an agent, a script, or a program.
On Windows it uses UI Automation for element discovery, SendInput for keyboard/mouse injection, and DXGI/GDI for screen capture. On Linux it uses AT-SPI2 over D-Bus for discovery and actions, XTEST (X11) or the RemoteDesktop portal / uinput (Wayland) for input, and X11 GetImage or the Screenshot portal for capture. The Linux engine is pure Rust - no -devel packages to install.
Ship it three ways:
ghost-mcpserver - the primary surface: a Model Context Protocol server for Claude Code, Claude Desktop, Codex, Cursor, and any MCP client (54 tools on Windows)ghostCLI - one-shot commands, great for scripts and CI (ghost click --name "Submit")ghost-httpserver - local REST API, call it from Python, Node, curl, anything (curl http://127.0.0.1:7878/list-windows)
The MCP surface is 20 desktop verbs, 19 ghost_browser_* / ghost_tab_* tools for
driving individual browser tabs in the background (Chrome, Comet, Edge, Brave), and
15 Windows-only tools: the focus policy plus ghost_desktop_* for explicit control of
isolated Windows desktops the user never sees. Under the default policy you rarely
need the latter: ghost_window op=launch already starts the app on the hidden
desktop auto, and ghost_see / ghost_act / ghost_key / ghost_scroll reach it
with window=<title> exactly as they reach a window on your own desktop
(target.surface in the response tells you which). UIA, window messages and capture
work fully there. Real SendInput does not, because Windows refuses it off the
input desktop, and typing is proven by reading the control's value back, so a target
that drops posted characters returns an error rather than a false success. The
desktop verbs and the browser tools build on Linux as well; the focus policy and
hidden desktops are Windows-only.
No Claude required. No browser required. No CDP. It drives apps through the OS's own automation and input APIs, so it works with native apps that have no API and no automation hooks of their own - the same reliability whether or not an app was built to be automated.
Platforms
| Platform | Status | Engine |
|---|---|---|
| Windows | ✅ full and verified | ghost-core - Win32 UI Automation, SendInput, posted window messages, DXGI/GDI capture |
| Linux, X11 | ✅ functional - verified by live CI tests against a real GTK app | ghost-linux - AT-SPI2 over D-Bus, XTEST input, X11 GetImage capture |
| Linux, Wayland | ⚠️ implemented, NOT verified - no test has run it on hardware | same AT-SPI2 discovery and actions; input and capture go through the RemoteDesktop / Screenshot portals or uinput instead |
| macOS | 🚧 scaffold | Accessibility + CGEvent + ScreenCaptureKit - to be built on a Mac |
Wayland deserves the separate row rather than a footnote: it is the default
session on current Ubuntu and Fedora, so it is what most Linux users would
actually run, and it is the part with no test behind it. The discovery and
action layer is shared with X11 and is covered, and it is the layer that
matters most here - AT-SPI2 asks the application to do the thing, so there is
no pointer to move and no window to raise. What is unverified is the fallback
underneath: portal input, portal capture, uinput. If you run Wayland, treat
ghost doctor as the first thing to run and expect to file bugs. Reports are
welcome and are the fastest way that row changes.
ghost-session and ghost-mcp are shared: the locator tiers, grounding cascade,
act-then-verify loop and the 20 core MCP verbs are written once and run on both
platforms. Only the engine underneath changes, behind a one-line cfg alias. The
browser and tab tools are engine-independent and build for both; the focus policy
and isolated desktops are Windows-only and are reported as such rather than faked.
The wedge survives the port. On Windows, driving an app without stealing focus is built on posted window messages. Linux has a cleaner analogue in AT-SPI2 actions: the application performs the operation through its own toolkit, so there is no pointer to move and no window to raise. That layer is the same code under X11 and Wayland; synthetic input is only the fallback beneath it, and the fallback is the part Wayland has not been tested on.
This is tested, not asserted: CI stands up a real desktop (Xvfb + D-Bus + at-spi-bus-launcher), drives a real GTK application, and requires that text written through AT-SPI reads back from the app and that invoking a button actually dismisses the dialog. Wayland portal input and capture are implemented but not yet verified on hardware.
Linux setup, verification checklist and honest limitations:
docs/linux-fedora.md. Capability matrix across all
three: docs/cross-platform.md.
Ghost is a general-purpose automation tool. Use it on systems you own or are authorized to automate, and in line with the terms of the software you drive.
Install
One-click - MCP Bundle (free). Every release ships ghost-windows-x64.mcpb and
ghost-linux-x86_64.mcpb on the Releases page.
Open one in a client that supports MCP Bundles (Claude Desktop: Settings -> Extensions ->
Install from file) and Ghost is registered, no PATH or config editing, and no API key. Ghost is also listed in
the MCP registry as io.github.NORTHTEKDevs/ghost,
so registry-aware clients can install it from there. The bundle holds the ghost-mcp server
only; the CLI and HTTP server are in the archives below.
Prebuilt binaries (free). Every release ships signed-by-checksum archives for both platforms on the Releases page:
# Linux x86_64
curl -LO https://github.com/NORTHTEKDevs/ghost/releases/latest/download/ghost-linux-x86_64.tar.gz
curl -LO https://github.com/NORTHTEKDevs/ghost/releases/latest/download/ghost-linux-x86_64.tar.gz.sha256
sha256sum -c ghost-linux-x86_64.tar.gz.sha256
tar -xzf ghost-linux-x86_64.tar.gz && ./install.sh
Windows: download ghost-windows-x64.zip from the same page. Verify the
checksum, unzip, and add the folder to your PATH. Then run ghost doctor.
Check where a download came from. Every release artifact carries a signed build provenance attestation, so you can prove a file came out of this repository's release workflow and nowhere else, at a named commit:
gh attestation verify ghost-windows-x64.mcpb --repo NORTHTEKDevs/ghost
The binaries are not code-signed yet, so Windows SmartScreen will warn you on first run (click More info
→ Run anyway). That warning is about publisher identity, which needs a paid certificate tied to a verified legal
entity; the attestation above is the stronger statement about origin and costs nothing, but Windows does not read it.
The pipeline signs the moment a certificate is configured, from any CA - see
docs/code-signing.md, and
docs/signing-policy.md for what gets signed, by
whom, and what leaves your machine (nothing, unless you configure a vision key). If an antivirus engine quarantines a release, verify the
checksum and see docs/antivirus.md for what the binaries do to stay recognisable and how
to report a false positive. The kit buys convenience, not capability - everything Ghost can do is in the free source
below, and building it yourself takes one command.
Option C - Build from source (free, MIT). Ghost is open source. Compile it yourself:
git clone https://github.com/NORTHTEKDevs/ghost
cd ghost
cargo build --release --bin ghost --bin ghost-http --bin ghost-mcp
# binaries in target/release/
Requirements: Windows 10 build 19041+, or Linux with at-spi2-core (and Rust
stable only if building from source).
On Linux:
sudo dnf install at-spi2-core xdg-desktop-portal xdg-desktop-portal-gnome
gsettings set org.gnome.desktop.interface toolkit-accessibility true
./scripts/install.sh # build, install, register the MCP server, run doctor
No -devel packages are needed - the Linux engine is pure Rust. Full setup and
troubleshooting: docs/linux-fedora.md.
Check your machine first:
ghost doctor
Reports PASS/WARN/FAIL and exits 1 if anything is FAIL. Run it before opening an issue - it usually names the problem outright.
- Windows: build version, interactive desktop, UI Automation, DPI awareness, monitor layout, screen capture, optional vision credentials.
- Linux: session type (X11/Wayland), AT-SPI bus reachability, whether applications are actually exposing accessible trees, the selected input backend, and screen capture.
Quick Start - coding agents and MCP clients
This is the path Ghost is built for. Nothing to configure and no API key.
Claude Desktop: download ghost-windows-x64.mcpb (or the Linux bundle) from the
latest release and open it:
Settings -> Extensions -> Install from file.
Claude Code:
claude mcp add ghost --scope user -- C:/path/to/ghost-mcp.exe
Any other MCP client (Codex, Cursor, a custom harness): register the binary as a stdio server.
{
"mcpServers": {
"ghost": { "command": "C:/path/to/ghost-mcp.exe" }
}
}
Ghost is also listed in the MCP registry
as io.github.NORTHTEKDevs/ghost for clients that install from there.
The repo's Dockerfile builds a headless image (docker build -t ghost-mcp .) that
answers initialize and tools/list with no display; registries and CI use it to
introspect the server. A container has no windows to drive, so it is not an install
path for real use.
How an agent uses it. The loop is look, act, confirm:
ghost_see window="Invoice Editor"- every element in the window with its name, role, enabled state, and on-screen centre. Text mode extracts the readable text instead, roughly ten times cheaper in tokens than an image.ghost_act window="Invoice Editor" name="Save" action="click"- Ghost drives the control in the background and returnsverified: trueonly when the screen or the control's value shows the action took.ghost_screenshot window="Invoice Editor"- pixels, for the moments a layout, a chart, or a canvas needs the model's own eyes.
The model reads step 1 and step 3 and chooses; Ghost never has to guess what a picture means, and no vision key is involved.
Beyond the loop: ghost_shell runs commands and persistent PowerShell sessions,
ghost_window launches, lists, focuses, restores and closes windows (on a hidden
desktop by default), ghost_assert and ghost_wait turn "did it work" into a
check, and the ghost_tab_* tools drive the browser you are already signed into.
Most real sessions spend more calls there than on looking.
54 tools on Windows (legacy names stay dispatchable): 20 desktop verbs covering
see/snapshot/find/act/keys/scroll/drag/clipboard/screenshot/windows/shell/waits/query/run,
19 ghost_browser_* / ghost_tab_* tools, and 15 Windows-only tools for the focus
policy and isolated desktops. Building from source instead of downloading:
cargo build -p ghost-mcp --release.
Every tool runs on its own task, so a slow call does not block a fast one, and a
second Ghost process can run alongside the first. Once it is mounted, run
ghost verify to audit that on your own machine.
Speed. Ghost's own time is small: about 75 ms for a text read, 200 ms for
a verified click, 1 ms to list windows. What makes an agent session slow is
what happens around the calls, and three habits remove most of it. Name the
window once and omit window= afterwards: the anchor follows that window by
handle, and a title it used to have still resolves instantly with
title_drift in the response. Wait for a condition, not a duration:
ghost_wait for=element, for=value, and for=navigate (sets the address
bar in the background and returns when the title changes, about 0.4 to 1.4 s
where a fixed sleep costs 6) return the moment the thing happened. Batch with
ghost_run so one model turn does several steps. scripts/speed-probe.mjs
measures all of this against any ghost-mcp binary.
Shell control (ghost_shell)
Ghost drives GUIs and the command line. ghost_shell runs terminal commands and
persistent PowerShell sessions - builds, git, CLIs, file edits on hosts without file
tools, or launching apps. op=run is a one-shot (powershell/pwsh/cmd); op=open
starts a persistent PowerShell whose variables and cwd survive across op=send calls.
Output is merged stdout+stderr, tail-capped for the agent's context window; a timed-out
command keeps running and is drained with op=read; ghost_stop kills a runaway.
op=run with the default powershell is served from a pre-spawned spare process, so
a command costs about 85 ms instead of the 230-450 ms a fresh PowerShell start takes
(the spare is single-use and replaced immediately; GHOST_SHELL_WARM=off disables it).
Spawn a fresh Claude Code session from the agent:
ghost_shell op=run cmd='Start-Process wt -ArgumentList "pwsh","-NoExit","-Command","claude"',
then drive the new terminal window with ghost_see / ghost_act / ghost_key.
Security: shell access is powerful. Set GHOST_SHELL=off in the server's env to
disable the verb entirely - every op then returns a clear refusal, leaving the GUI
automation verbs fully usable.
Quick Start - CLI
# Launch Notepad and type into it
ghost launch notepad.exe
ghost focus-window "Notepad"
ghost type --role edit --text "hello from ghost"
# Keys and hotkeys
ghost press Enter
ghost hotkey --mods Ctrl --key s
# Screenshot
ghost screenshot --out shot.png
# Enumerate windows or UI
ghost list-windows
ghost describe --window "Notepad"
# Click at coords or by name
ghost click-at 500 300
ghost click --name "Save"
# Run a JSON intent (finite-state machine with retries, timeouts, conditions)
ghost run my-flow.json
echo '{"ops":[{"op":"launch","exe":"notepad.exe"}]}' | ghost run -
Everything outputs JSON for easy piping into jq or scripts.
Quick Start - HTTP Server
Start the server:
ghost-http --addr 127.0.0.1:7878
Then from any language:
# Bash / curl
curl http://127.0.0.1:7878/list-windows
curl -X POST http://127.0.0.1:7878/click \
-H 'content-type: application/json' \
-d '{"name":"Submit"}'
curl http://127.0.0.1:7878/screenshot -o shot.png
# Python
import requests
requests.post("http://127.0.0.1:7878/launch", json={"exe": "notepad.exe"})
requests.post("http://127.0.0.1:7878/type",
json={"role": "edit", "text": "hello from python"})
// Node
await fetch("http://127.0.0.1:7878/hotkey", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ mods: ["Ctrl"], key: "s" }),
});
Endpoints: /health, /tools, /click, /click-at, /type, /press, /hotkey, /screenshot, /launch, /list-windows, /focus-window, /window-state, /describe, /clipboard (GET/POST), /run.
Quick Start - Rust SDK
[dependencies]
ghost-session = { git = "https://github.com/NORTHTEKDevs/ghost" }
use ghost_session::{GhostSession, By, session::Region};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let session = GhostSession::new()?;
session.launch("notepad.exe").await?;
let edit = session.find(By::role("edit")).await?;
edit.type_text("hello world")?;
let png = session.screenshot(Region::full()).await?;
std::fs::write("screen.png", png)?;
Ok(())
}
Ghost MCP 질문
작업 중에 Ghost가 마우스와 키보드를 제어하나요?
아니요, Ghost는 포커스를 뺏거나 커서를 움직이지 않고 백그라운드에서 실행되도록 설계되었습니다. 사용자가 다른 윈도우에서 작업을 계속하는 동안 window message와 UI Automation을 사용하여 앱과 상호작용합니다.
Ghost는 작업이 실제로 성공했는지 어떻게 확인하나요?
Ghost는 act-then-verify 루프를 사용합니다. 작업 후 화면을 다시 확인하거나 컨트롤의 값을 다시 읽어와 작업이 제대로 수행되었는지 확인합니다.