Ghost MCP F1b32c90

MCP运维云端

提供方 PIsberg

运维云端 未标注 Token 社区 / 第三方 Claude DesktopClaude

Ghost MCP是一款提供操作系统级UI自动化能力的服务器,允许AI客户端控制鼠标、键盘和屏幕,适用于无API的传统应用自动化、GUI测试等场景。

一句话选型结论

按资料字段整理

Ghost MCP F1b32c90 属于运维云端类 MCP 服务器,传输方式未标注,Token,可直接接入 Claude Desktop、Claude,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类运维云端 传输方式未标注 鉴权Token 部署方式未标注
GitHub 星标 2 仓库热度,无公开仓库时显示未标注
工具数 26 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

运维云端
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量26暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

UI自动化Go本地部署AI控制GUI测试鼠标键盘控制OCR识别

安装与配置

未标注 Token
上游未给出传输方式
  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 26 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
云资源查询

查实例、存储、账单等云上资源状态。

部署与发布

把部署、重启、回滚这类操作接进对话。

监控与告警

拉取监控指标,异常时让模型帮你判断。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 26 个工具,覆盖面较广,能满足多种调用。
  • 已适配 Claude Desktop、Claude,换客户端不用重新研究配置。

先想清楚的地方

  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在运维云端场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Ghost MCP F1b32c90当前 26 未标注 未标注 无 2026-05-17
lobehub 未标注 stdio · 本地进程 本地部署 有 2026-04-11
TrendRadar 未标注 stdio · 本地进程 本地部署 有 2026-04-13
Ui Tars Desktop 8a825770 未标注 stdio · 本地进程 本地部署 有 2026-05-17
ruflo 未标注 stdio · 本地进程 本地部署 有 2026-04-13
FastGPT 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

运维云端
字段来自项目仓库与公开索引,中文说明由本站标注
提供方PIsberg上游标注的维护方 PIsberg
分类运维云端本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

32.2 KB
来自项目仓库与上游目录的原文,未做删改

Ghost MCP Server

The Ghost in the Machine - An MCP (Model Context Protocol) server that exposes OS-level UI automation capabilities to AI clients.

License: Free for personal and hobby use (PolyForm Noncommercial). Commercial use requires a license — contact Peter Isberg.

Overview

Ghost MCP allows AI assistants like Claude to control your computer's mouse, keyboard, and screen. This enables automation of legacy applications, GUI testing, and any task that requires interacting with applications that don't have APIs.

Features

  • 🖱️ Mouse Control: Move cursor, click, double-click, scroll
  • ⌨️ Keyboard Control: Type text, press individual keys
  • 📸 Screen Capture: Take screenshots with optional region selection
  • 🔍 OCR: Find screen text and UI elements with Tesseract (always built in)
  • 🔐 Token Authentication: Requires a secret token before the server will start
  • 📋 Audit Logging: Tamper-evident JSON Lines log of every tool call, auth failure, and lifecycle event
  • 🛡️ Failsafe: Emergency shutdown by moving mouse to top-left corner (0,0)
  • 📝 Structured Storytelling Logging: Narrative-driven audit of agent actions written to stderr and a configurable log file.
  • 🌐 Dual Transport: stdio (default) or HTTP/SSE for web-based clients

Available Tools

> AI routing guide: Before automating a UI, read docs/routing_prompt.md for critical safety rules, decision tables, optimal tool sequences, and when to use learning mode. The server also delivers this guide automatically to AI clients via the ghost_mcp_guide MCP prompt on connect.

Tool Description Parameters OCR
get_screen_size Get screen resolution and DPI scale factor. None —
move_mouse Move mouse cursor to absolute coordinates or Visual ID. x, y, id —
click Click mouse at current cursor position. Use move_mouse first. button (left/right/middle) —
click_at Move mouse to coordinates or Visual ID and click in one operation. x, y, id, button —
double_click Move mouse to coordinates or Visual ID and double-click. x, y, id —
scroll Move mouse to (x, y) and scroll. 🚫 NO-PEEK RULE: Do not use for peeking after learn_screen. x, y, direction, amount —
type_text Type text via keyboard into focused element. text, press_enter —
click_and_type Move mouse to coordinates or Visual ID, click, and type. x, y, id, text, button, delay_ms, press_enter —
press_key Press a single key or shortcut (e.g. Enter, Tab, Ctrl+C). key —
take_screenshot Capture raw screenshot. Visual-only tasks. 🚫 NOT FOR UI ANALYSIS. Use get_annotated_view for IDs. x, y, width, height, quality —
scroll_until_text Scroll in one bounded call until OCR finds the target text or max_scrolls is reached. text, direction, amount, max_scrolls, scroll_x, scroll_y, x, y, width, height, nth, grayscale, element_type ✓
find_elements Read all visible text elements with coordinates and types. Fast alternative to screenshots for understanding screen content. x, y, width, height, element_type ✓
find_and_click Find text on screen and click its center. Smart matching, auto-cached regions (10–25× faster on repeat), loop protection (max 25 calls/session). text, button, nth, x, y, width, height, element_type, scroll_direction, max_scrolls, next_page_keys, max_pages, select_best ✓
find_click_and_type Find a label or placeholder, click the associated input field, and type immediately. text, type_text, x_offset, y_offset, press_enter, delay_ms, scroll_direction, scroll_amount, max_scrolls, scroll_x, scroll_y, element_type ✓
find_and_click_all Click multiple distinct elements atomically in one call. Use for checking several checkboxes or clicking a sequence of known buttons — not for trying alternative labels. texts (array), button, delay_ms, element_type ✓
wait_for_text Wait for text to appear or disappear. Always use this after actions that trigger a UI change instead of fixed delays. text, visible, timeout_ms, x, y, width, height, element_type ✓
click_until_text_appears Click coordinates and retry until confirmation text appears or max_clicks is reached. Prevents infinite click loops. x, y, wait_for_text, button, timeout_ms, max_clicks ✓
execute_workflow Execute multiple sequential steps sharing one learned screen map. 3–6× faster than individual calls when all steps are on the same screen. steps (array), clear_view_after ✓
learn_screen Scan UI: Index full interface (all scroll pages) and cache element map. Default max_pages: 3. x, y, width, height, max_pages, scroll_amount ✓
get_learned_view Map Text/IDs: Return machine-readable inventory of all elements (on and off-screen). None —
get_annotated_view Verify IDs: Return screenshot with [ID] visual_id overlays. ONLY source for interactive IDs. page_index, x, y, width, height ✓
clear_learned_view Discard the current learned view. Call after navigation or significant UI changes to prevent stale positions. None —
set_learning_mode Enable or disable learning mode at runtime. When enabled, the first OCR call auto-scans the screen. enabled —
smart_click Convenience wrapper: runs learn_screen then find_and_click in one call. Use for a single click on an unfamiliar screen; use learn_screen explicitly for multi-step sessions. text, button, nth ✓
get_region_cache_stats Return cache statistics (hits, misses, hit rate). Use to monitor region cache effectiveness. None —
clear_region_cache Clear all cached regions. Use after screen resolution changes or UI layout rearrangement. None —

> Tesseract required: tools marked ✓ in the OCR column require Tesseract to be installed and TESSDATA_PREFIX set. The installation scripts handle this automatically. See Prerequisites.

🛡️ Safety Features & Loop Protection

Ghost MCP includes built-in safeguards to prevent infinite retry loops and runaway automation:

Global Call Limit (25 calls/session)```

WARNING: Only 5 tool calls remaining before forced stop.
MAXIMUM TOOL CALLS REACHED (25). Stop and try a completely different approach.


#### Consecutive Failure Detection (3 strikes)```
GIVE UP RECOMMENDATION: Failed 3 times with "Submit". STOP trying this text.
Try: (1) find_elements to see actual text, (2) shorter search term,
(3) scroll_direction if off-screen, or (4) completely different approach.

Repeated Click Detection (5 clicks at same spot)```json

{
"success": true,
"warning": {
"should_stop": true,
"reason": "Clicked same coordinates (403,767) 5 times in 30 seconds",
"click_count": 5,
"message": "You've clicked this spot 5 times. Verify this is correct before continuing."
}
}


#### Enhanced Error Responses
Every error now includes:
- `consecutive_failures`: How many times this search failed
- `remaining_calls`: Calls left before forced stop
- `suggestion`: Actionable next step (`scroll_may_help`, `no_matches_found`, etc.)
- `candidates`: All OCR-detected text with confidence scores

#### Response Example on Failure```json
{
  "error": "text \"Submit\" not found...",
  "candidates": [
    {"text": "Submit", "score": 100, "x": 50, "y": 50}
  ],
  "suggestion": "scroll_may_help",
  "consecutive_failures": 2,
  "remaining_calls": 18
}

🎯 Smart OCR Matching

Ghost MCP uses an intelligent scoring system to find the best match for your text:

How it works:
Instead of simple substring matching, every OCR-detected word is scored:

Score Match Type Example
1000 Exact match Searching "Click Me!" finds "Click Me!"
500 Prefix match Searching "Click" finds "Click Me!"
400 Suffix match Searching "Click" finds "Button Click"
300 Standalone word Searching "Click" finds "Button Click" (separate word)
200 Multi-word (all found) Searching "Save Changes" finds both words
100 Substring with boundaries Weaker match
50 Inside another word Lowest priority (avoided)

Why it matters:```
❌ OLD BEHAVIOR: Search "Click" → clicks "Button Click Tests" header
✅ NEW BEHAVIOR: Search "Click" → clicks standalone "Click Me!" button


The system:
1. Scores all matches using the table above
2. Sorts by score (best first), then by area (smaller = more precise)
3. Returns the best match for your click

**Production-ready:** Handles real-world UI with headers, labels, and buttons that share common text.

### ⚡ Performance Optimization: Region Cache

Ghost MCP automatically optimizes repeated UI interactions using **region caching**:

**How it works:**
1. When `find_and_click` successfully finds a button, it caches the screen region
2. Subsequent calls with the same text scan only the cached region (not the full screen)
3. Cache entries include screen resolution — automatically invalidated if resolution changes
4. LRU eviction keeps the 100 most recently used entries

**Performance impact:**
- **First call:** Full screen OCR scan (~1920×1080)
- **Cached calls:** Small region scan (~100×50) — **10-25x faster**

**Monitoring cache:**```json
// Check cache statistics
{
  "tool": "get_region_cache_stats"
}
// Response: {"entries":5,"hits":12,"misses":3,"hit_rate":80.0,"evictions":0}

When to clear cache:
- Screen resolution changed
- UI layout was significantly rearranged
- Cache returning stale results```json
// Clear all cached regions
{
"tool": "clear_region_cache"
}
// Response: {"success":true,"message":"Region cache cleared"}


**Cache behavior:**
- Case-insensitive: "Save", "SAVE", "save" use the same entry
- Auto-invalidates on screen resolution change
- 24-hour expiration for stale entries
- Thread-safe with RWMutex protection

### 🎯 Element Type Filtering

Ghost MCP supports **element type filtering** to target specific UI component types in search operations. This allows you to narrow results to only the type of element you're looking for, improving accuracy and reducing false matches.

**Supported element types:**

| Type | Description | Example Use Case |
|------|-------------|------------------|
| `button` | Clickable action elements | "Submit", "Save", "Cancel" buttons |
| `input` | Text input fields | Form fields, search boxes |
| `checkbox` | Checkboxes (☐ ☑ ✓) | Agreement checkboxes, toggles |
| `radio` | Radio buttons (○ ● ◉) | Single-selection option groups |
| `dropdown` | Dropdown menus (▼) | Select menus, comboboxes |
| `toggle` | Toggle switches (ON/OFF) | Settings toggles, switches |
| `slider` | Sliders/range controls | Volume sliders, range inputs |
| `label` | Field labels (usually ending with ":") | "Email:", "Name:" labels |
| `heading` | Section/page headings | Page titles, section headers |
| `link` | Hyperlinks | Navigation links, anchor text |
| `value` | Numeric or status values | Prices, scores, counters |
| `text` | General body text | Paragraphs, descriptions |

**Usage examples:**```json
// Find only buttons, ignoring labels and headings that contain the same text
{
  "tool": "find_and_click",
  "arguments": {
    "text": "Save",
    "element_type": "button"
  }
}

// Get all input fields on a form
{
  "tool": "find_elements",
  "arguments": {
    "element_type": "input"
  }
}

// Wait for a specific label to appear
{
  "tool": "wait_for_text",
  "arguments": {
    "text": "Success:",
    "element_type": "label"
  }
}

// Find and type into an input field
{
  "tool": "find_click_and_type",
  "arguments": {
    "text": "Email:",
    "type_text": "user@example.com",
    "element_type": "input"
  }
}

How it works:
- Element types are inferred from text patterns, dimensions, and context
- Filtering happens during OCR processing — only matching elements are returned
- Works with all search features: scrolling, multi-page, and caching
- If no element of the specified type is found, returns "not found" error

When to use:
- Multiple elements share the same text but have different types (e.g., "Submit" as both a button and a label)
- You want to target only specific UI components
- You need to discover all form fields, buttons, or other specific element types

Prerequisites

The installation scripts (install.ps1 for Windows, install.sh for Linux) automatically install all required dependencies.

If building manually, you'll need:

  • Go 1.24+ - Download Go
  • C Compiler - For RobotGo (GUI automation library)
  • Tesseract OCR + Leptonica - Required for OCR tools (find_elements, find_and_click); always built in

Platform-Specific Dependencies

Windows

Required: MinGW-w64 GCC Compiler

Install via Chocolatey (recommended):```powershell

Run as Administrator

choco install mingw -y


**Tesseract OCR** is required (always built in). Install via vcpkg (the install script does this automatically):```powershell
# Install vcpkg and Tesseract (MinGW-compatible triplet)
git clone https://github.com/Microsoft/vcpkg.git $env:USERPROFILE\vcpkg
cd $env:USERPROFILE\vcpkg
.\bootstrap-vcpkg.bat -disableMetrics
$env:CC  = "C:\ProgramData\mingw64\mingw64\bin\gcc.exe"
$env:CXX = "C:\ProgramData\mingw64\mingw64\bin\g++.exe"
.\vcpkg install tesseract:x64-mingw-dynamic leptonica:x64-mingw-dynamic

# Download English language data for Tesseract
$tessdata = "$env:USERPROFILE\vcpkg\installed\x64-mingw-dynamic\share\tessdata"
Invoke-WebRequest "https://github.com/tesseract-ocr/tessdata_fast/raw/main/eng.traineddata" -OutFile "$tessdata\eng.traineddata"

# Set required environment variables (persist across reboots)
[System.Environment]::SetEnvironmentVariable("TESSDATA_PREFIX", "$env:USERPROFILE\vcpkg\installed\x64-mingw-dynamic\share\tessdata", "User")
[System.Environment]::SetEnvironmentVariable("CGO_CPPFLAGS", "-I$env:USERPROFILE/vcpkg/installed/x64-mingw-dynamic/include", "User")
[System.Environment]::SetEnvironmentVariable("CGO_LDFLAGS",  "-L$env:USERPROFILE/vcpkg/installed/x64-mingw-dynamic/lib", "User")

macOS```bash

Install Xcode Command Line Tools

xcode-select --install

Tesseract OCR (required)

brew install tesseract leptonica

Grant accessibility permissions (required for automation)

System Settings → Privacy & Security → Accessibility → Add Terminal/your IDE


#### Linux

**Ubuntu/Debian:**```bash
# X11 automation libraries
sudo apt-get install libx11-dev xorg-dev libxtst-dev libpng-dev
# Tesseract OCR (required)
sudo apt-get install tesseract-ocr libleptonica-dev libtesseract-dev

Fedora:```bash
sudo dnf install libX11-devel libXtst-devel libpng-devel
sudo dnf install tesseract tesseract-devel leptonica-devel


**Arch Linux:**```bash
sudo pacman -S libx11 libxtst libpng
sudo pacman -S tesseract tesseract-data-eng

Installation

Quick Install (Recommended)

We provide automated installation scripts that handle all dependencies and configuration:

Windows```powershell

Run PowerShell as Administrator

.\install.ps1


The installer will:
- Install MinGW (GCC compiler) via Chocolatey
- Install Tesseract OCR via vcpkg (x64-mingw-dynamic triplet)
- Download English language data (`eng.traineddata`) and set `TESSDATA_PREFIX`
- Build the binary and copy runtime DLLs
- Generate auth token
- Configure environment variables
- Display MCP client configuration

#### Linux```bash
chmod +x install.sh
./install.sh

The installer will:
- Detect your package manager (apt/dnf/yum/pacman/zypper)
- Install GCC, X11 development libraries, and Tesseract OCR
- Build the binary
- Generate auth token
- Save environment configuration to ~/.config/ghost-mcp/env
- Display MCP client configuration

OCR Support

OCR (find_elements, find_and_click) is always built in. The installer sets up Tesseract automatically, including downloading the English language data file and setting TESSDATA_PREFIX.

Manual Build

If you prefer to build manually:```bash

Clone or navigate to the project directory

cd ghost-mcp

Download dependencies

go mod download

Build (Windows — requires MinGW and Tesseract via vcpkg, see Prerequisites)

go build -o ghost-mcp.exe ./cmd/ghost-mcp/

Build (macOS/Linux)

go build -o ghost-mcp ./cmd/ghost-mcp/


On Windows, set `CGO_CPPFLAGS` and `CGO_LDFLAGS` before building (see the Windows prerequisites section above). Also copy the runtime DLLs next to the binary:```powershell
Copy-Item "$env:USERPROFILE\vcpkg\installed\x64-mingw-dynamic\bin\*.dll" . -Force

Configuration

MCP Client Configuration (mcp.json)

Add this to your MCP client configuration to connect to Ghost MCP:

For Claude Desktop (Windows)```json

{
"mcpServers": {
"ghost-mcp": {
"command": "C:\path\to\ghost-mcp.exe",
"args": [],
"env": {
"GHOST_MCP_TOKEN": "your-secret-token-here",
"TESSDATA_PREFIX": "C:\Users\<you>\vcpkg\installed\x64-mingw-dynamic\share\tessdata"
}
}
}
}


#### For Claude Desktop (macOS/Linux)```json
{
  &quot;mcpServers&quot;: {
    &quot;ghost-mcp&quot;: {
      &quot;command&quot;: &quot;/absolute/path/to/ghost-mcp&quot;,
      &quot;args&quot;: [],
      &quot;env&quot;: {
        &quot;GHOST_MCP_TOKEN&quot;: &quot;your-secret-token-here&quot;,
        &quot;TESSDATA_PREFIX&quot;: &quot;/usr/share/tesseract-ocr/5/tessdata&quot;
      }
    }
  }
}

> Replace your-secret-token-here with the same value you generated for GHOST_MCP_TOKEN.

Configuration File Locations

Platform Config Location
Windows %APPDATA%\Claude\mcp.json
macOS ~/Library/Application Support/Claude/mcp.json
Linux ~/.config/Claude/mcp.json

Environment Variables

Variable Description Default
GHOST_MCP_TOKEN Required. Secret authentication token. Server refuses to start without it. (none — must be set)
TESSDATA_PREFIX Required for OCR. Directory that directly contains eng.traineddata (NOT its parent). (none — OCR will fail if unset)
GHOST_MCP_OCR_FORMAT Injection format for sending screen buffers to OCR engine natively (bmp or png) bmp (lossless, uncompressed speed)
GHOST_MCP_AUDIT_LOG Directory for audit log files. Created automatically if absent. /ghost-mcp/audit/
GHOST_MCP_LOG_FILE Path to the storyteller log file. application.log
GHOST_MCP_LOG_LEVEL Log verbosity (DEBUG, INFO, WARN, ERROR). INFO
GHOST_MCP_VISUAL Show visual cursor pulse on mouse actions (1 = on) 0 (disabled)
GHOST_MCP_KEEP_SCREENSHOTS Keep screenshot files on disk after use (1 = keep, default deletes them) 0 (deleted after use)
GHOST_MCP_SCREENSHOT_DIR Directory where screenshot files are written System temp directory
GHOST_MCP_TRANSPORT Transport mode: stdio or http stdio
GHOST_MCP_HTTP_ADDR Listen address for HTTP/SSE mode localhost:8080
GHOST_MCP_HTTP_BASE_URL Public base URL advertised to SSE clients http://
GHOST_MCP_LEARNING Learning mode (0 = off, 1 = on). When on, the first OCR call auto-scans the screen and all subsequent calls use the cached element map (10–25× faster). 1 (on by default; set 0 to disable)
GHOST_MCP_DPI_AWARE Windows only: 1 declares per-monitor-v2 DPI awareness at startup so captures cover the physical desktop on scaled displays. Changes the capture/click coordinate space; verify against your setup. 0 (off)
GHOST_MCP_CV_ICONS Shape detection during learn_screen: icons and empty input boxes become clickable text-less elements. Set 0 to disable. on
GHOST_MCP_CV_BUTTONS Region-proposal OCR during learn_screen: saturated colour buttons (whose labels full-image OCR drops) are cropped and read at native scale. Set 0 to disable. on

> Security note: GHOST_MCP_TOKEN must be set to a random secret. Generate one with:
>bash &gt; # Linux/macOS &gt; export GHOST_MCP_TOKEN=$(openssl rand -hex 32) &gt; &gt; # Windows (PowerShell) &gt; $env:GHOST_MCP_TOKEN = -join ((1..32) | % { &#x27;{0:x}&#x27; -f (Get-Random -Max 256) }) &gt;
> Then add it to the env block of your MCP client configuration (see examples below).

Usage

Starting the Server

The server runs via stdio and is typically started by your MCP client automatically. To test manually:```bash

Run the server (will wait for stdin/stdout communication)

./ghost-mcp

With debug logging

GHOST_MCP_LOG_LEVEL=DEBUG ./ghost-mcp


### Example Tool Calls

Once connected, AI clients can use the tools like this:```json
// Find text on screen and click it — start here for any click task
{
  &quot;tool&quot;: &quot;find_and_click&quot;,
  &quot;arguments&quot;: {&quot;text&quot;: &quot;Save&quot;}
}
// Response: {&quot;success&quot;: true, &quot;found&quot;: &quot;Save&quot;, &quot;x&quot;: 960, &quot;y&quot;: 540, &quot;button&quot;: &quot;left&quot;, &quot;occurrence&quot;: 1}
// If not found, the error includes closest OCR matches and the searched region.

// Move and click in one call
{
  &quot;tool&quot;: &quot;click_at&quot;,
  &quot;arguments&quot;: {&quot;x&quot;: 960, &quot;y&quot;: 540, &quot;button&quot;: &quot;left&quot;}
}
// Response: {&quot;success&quot;: true, &quot;button&quot;: &quot;left&quot;, &quot;x&quot;: 960, &quot;y&quot;: 540}

// Double-click to open a file
{
  &quot;tool&quot;: &quot;double_click&quot;,
  &quot;arguments&quot;: {&quot;x&quot;: 960, &quot;y&quot;: 540}
}
// Response: {&quot;success&quot;: true, &quot;x&quot;: 960, &quot;y&quot;: 540}

// Scroll down in a list
{
  &quot;tool&quot;: &quot;scroll&quot;,
  &quot;arguments&quot;: {&quot;x&quot;: 960, &quot;y&quot;: 540, &quot;direction&quot;: &quot;down&quot;, &quot;amount&quot;: 5}
}
// Response: {&quot;success&quot;: true, &quot;x&quot;: 960, &quot;y&quot;: 540, &quot;direction&quot;: &quot;down&quot;, &quot;amount&quot;: 5}

// Type text into the focused field
{
  &quot;tool&quot;: &quot;type_text&quot;,
  &quot;arguments&quot;: {&quot;text&quot;: &quot;Hello, World!&quot;}
}
// Response: {&quot;success&quot;: true, &quot;characters_typed&quot;: 13}

// Press Enter key
{
  &quot;tool&quot;: &quot;press_key&quot;,
  &quot;arguments&quot;: {&quot;key&quot;: &quot;enter&quot;}
}
// Response: {&quot;success&quot;: true, &quot;key&quot;: &quot;enter&quot;}

// Take screenshot — returns JSON metadata + PNG image content
{
  &quot;tool&quot;: &quot;take_screenshot&quot;
}
// Response: {&quot;success&quot;: true, &quot;filepath&quot;: &quot;/tmp/ghost-mcp-screenshot-....png&quot;, &quot;width&quot;: 1920, &quot;height&quot;: 1080}
// (image data returned as a separate image/png content block)

// Find all text elements on screen
{
  &quot;tool&quot;: &quot;find_elements&quot;
}
// Response: {&quot;success&quot;: true, &quot;elements&quot;: [{&quot;text&quot;: &quot;Save&quot;, &quot;x&quot;: 940, &quot;y&quot;: 530, &quot;width&quot;: 40, &quot;height&quot;: 20, &quot;center_x&quot;: 960, &quot;center_y&quot;: 540, &quot;confidence&quot;: 98.5}, ...]}

Security

🔐 Token Authentication

Ghost MCP controls your mouse, keyboard, and screen — so it requires authentication before it will serve any requests.

How it works:

  1. Set GHOST_MCP_TOKEN to a random secret string in your shell and in your MCP client's env config block.
  2. The server reads the token at startup and refuses to start if it is not set.
  3. Every MCP request is validated against the startup token via a server hook. If the environment variable is cleared or altered after startup, all subsequent requests are rejected.

What this protects against:
- Running the server without prior configuration (no token → no service)
- Unauthorized processes that can execute the binary but don't know the token value

Generating a token:```bash

Linux/macOS

openssl rand -hex 32

Windows (PowerShell)

-join ((1..32) | % { '{0:x}' -f (Get-Random -Max 256) })


Use the output as the value for `GHOST_MCP_TOKEN` in both your shell environment and your MCP client&#x27;s `env` block.

### 📋 Audit Logging

Ghost MCP writes a tamper-evident audit trail for every event: tool invocations, authentication failures, client connections, and server lifecycle events.

**Log format:** JSON Lines (one JSON object per line), one file per UTC day.

**Default location:**

| Platform | Default path |
|----------|-------------|
| Windows | `%AppData%\ghost-mcp\audit\ghost-mcp-audit-YYYY-MM-DD.jsonl` |
| macOS | `~/Library/Application Support/ghost-mcp/audit/ghost-mcp-audit-YYYY-MM-DD.jsonl` |
| Linux | `~/.config/ghost-mcp/audit/ghost-mcp-audit-YYYY-MM-DD.jsonl` |

Override with `GHOST_MCP_AUDIT_LOG=/your/dir`.

**Example log entries:**```jsonc
// Server startup
{&quot;seq&quot;:1,&quot;timestamp&quot;:&quot;2025-01-15T09:00:00.123Z&quot;,&quot;event&quot;:&quot;SERVER_START&quot;,&quot;params&quot;:{&quot;platform&quot;:&quot;linux/amd64&quot;,&quot;version&quot;:&quot;1.0.0&quot;},&quot;prev_hash&quot;:&quot;0000...&quot;,&quot;hash&quot;:&quot;a3f2...&quot;}

// Client connected (from MCP initialize handshake)
{&quot;seq&quot;:2,&quot;timestamp&quot;:&quot;2025-01-15T09:00:01.456Z&quot;,&quot;event&quot;:&quot;CLIENT_CONNECTED&quot;,&quot;client_id&quot;:&quot;claude-desktop&quot;,&quot;params&quot;:{&quot;client_name&quot;:&quot;claude-desktop&quot;,&quot;client_version&quot;:&quot;1.0&quot;},&quot;prev_hash&quot;:&quot;a3f2...&quot;,&quot;hash&quot;:&quot;b7c1...&quot;}

// Tool invocation with parameters
{&quot;seq&quot;:3,&quot;timestamp&quot;:&quot;2025-01-15T09:00:05.789Z&quot;,&quot;event&quot;:&quot;TOOL_CALL&quot;,&quot;tool&quot;:&quot;type_text&quot;,&quot;client_id&quot;:&quot;claude-desktop&quot;,&quot;params&quot;:{&quot;text&quot;:&quot;Hello world&quot;},&quot;prev_hash&quot;:&quot;b7c1...&quot;,&quot;hash&quot;:&quot;c9d4...&quot;}

// Screenshot audit trail
{&quot;seq&quot;:4,&quot;timestamp&quot;:&quot;2025-01-15T09:00:06.012Z&quot;,&quot;event&quot;:&quot;SCREENSHOT_REQUESTED&quot;,&quot;tool&quot;:&quot;take_screenshot&quot;,&quot;client_id&quot;:&quot;claude-desktop&quot;,&quot;prev_hash&quot;:&quot;c9d4...&quot;,&quot;hash&quot;:&quot;d2e5...&quot;}

// Authentication failure
{&quot;seq&quot;:5,&quot;timestamp&quot;:&quot;2025-01-15T09:00:10.345Z&quot;,&quot;event&quot;:&quot;AUTH_FAILURE&quot;,&quot;error&quot;:&quot;invalid or missing GHOST_MCP_TOKEN&quot;,&quot;prev_hash&quot;:&quot;d2e5...&quot;,&quot;hash&quot;:&quot;e8f3...&quot;}

Tamper detection: Each entry carries:
- hash — SHA-256 of the entry's own content
- prev_hash — hash of the previous entry (hash chain)

If any entry is modified, deleted, or reordered, the chain breaks. Verify a log file with:```bash

Verify integrity of a specific log file

(built-in to the ghost-mcp source — see VerifyLogFile in audit.go)

go run . verify-log /path/to/ghost-mcp-audit-2025-01-15.jsonl


**Logged events:**

| Event | Trigger |
|-------|---------|
| `SERVER_START` | Server starts |
| `SERVER_STOP` | Server shuts down |
| `CLIENT_CONNECTED` | MCP initialize handshake completes |
| `TOOL_CALL` | Tool invoked (includes sanitized parameters) |
| `TOOL_SUCCESS` | Tool completed successfully |
| `TOOL_FAILURE` | Tool returned an error result |
| `SCREENSHOT_REQUESTED` | `take_screenshot` tool succeeded |
| `AUTH_FAILURE` | Request rejected due to missing/invalid token |
| `REQUEST_ERROR` | MCP-level error (unknown tool, malformed request) |

## HTTP/SSE Transport

By default Ghost MCP communicates over stdio, which is the standard MCP transport used by Claude Desktop. Set `GHOST_MCP_TRANSPORT=http` to start an HTTP/SSE server instead.

### Configuration```json
{
  &quot;mcpServers&quot;: {
    &quot;ghost-mcp&quot;: {
      &quot;command&quot;: &quot;C:\\path\\to\\ghost-mcp.exe&quot;,
      &quot;env&quot;: {
        &quot;GHOST_MCP_TOKEN&quot;: &quot;your-secret-token-here&quot;,
        &quot;GHOST_MCP_TRANSPORT&quot;: &quot;http&quot;,
        &quot;GHOST_MCP_HTTP_ADDR&quot;: &quot;localhost:8080&quot;,
        &quot;GHOST_MCP_HTTP_BASE_URL&quot;: &quot;http://localhost:8080&quot;
      }
    }
  }
}

Endpoints

Endpoint Method Description
/sse GET Open SSE stream (MCP connection)
/message POST Send MCP messages

Authentication

HTTP mode uses the same GHOST_MCP_TOKEN as Bearer authentication. Every request must include:```
Authorization: Bearer <your-token>


Requests without a valid Bearer token are rejected with HTTP 401 and logged as `AUTH_FAILURE` events in the audit log.

### Example with curl```bash
# Open SSE stream (keep this running in a terminal)
curl -N -H &quot;Authorization: Bearer $GHOST_MCP_TOKEN&quot; http://localhost:8080/sse

# Send an MCP initialize message
curl -X POST \
  -H &quot;Authorization: Bearer $GHOST_MCP_TOKEN&quot; \
  -H &quot;Content-Type: application/json&quot; \
  -d &#x27;{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;id&quot;:1,&quot;method&quot;:&quot;initialize&quot;,&quot;params&quot;:{&quot;protocolVersion&quot;:&quot;2024-11-05&quot;,&quot;clientInfo&quot;:{&quot;name&quot;:&quot;test&quot;,&quot;version&quot;:&quot;1.0&quot;},&quot;capabilities&quot;:{}}}&#x27; \
  &quot;http://localhost:8080/message?sessionId=&lt;session-id-from-sse&gt;&quot;

Safety Features

🛡️ Failsafe Mechanism

Ghost MCP includes an emergency shutdown feature:

  • Trigger: Move your mouse to the absolute top-left corner of the screen (coordinates 0,0)
  • Effect: The server will log an error and initiate graceful shutdown
  • Purpose: Prevents runaway AI automation loops from causing damage```
    ⚠️ WARNING: Do not move your mouse to (0,0) during normal operation!

### 📝 Structured Storytelling Logging

Ghost MCP implement a unique &quot;storytelling&quot; approach to logging. Instead of dry technical errors, `INFO` logs narrate the agent&#x27;s intent, progress, and outcomes in a narrative style.

**How it works:**
1. All logs are written to **stderr** (as required by the MCP protocol to keep stdout clean).
2. All logs are simultaneously written to a **narrative log file** (default: `application.log`).

Check the log file for a blow-by-blow account of the agent&#x27;s &quot;journey&quot;:```text
time=2024-04-06T19:26:26 level=INFO msg=&quot;Agent is searching for &#x27;Submit&#x27; button&quot;
time=2024-04-06T19:26:27 level=INFO msg=&quot;Success: Found &#x27;Submit&#x27; at (450, 720)&quot;
time=2024-04-06T19:26:27 level=INFO msg=&quot;ACTION COMPLETE: find_and_click &#x27;Submit&#x27; at (450, 720)&quot;

Troubleshooting

Common Issues

"Permission Denied" or "Access Denied"

  • macOS: Grant accessibility permissions in System Settings
  • Linux: Ensure you have X11 permissions (xhost + for testing)
  • Windows: Run as Administrator if needed

"RobotGo initialization failed"

  • Verify platform-specific dependencies are installed (see Prerequisites)
  • Check that no other application is blocking accessibility APIs

MCP Client Can't Connect

  • Verify the binary path in mcp.json is correct
  • Ensure the binary is executable (chmod +x ghost-mcp on Unix)
  • Check that no firewall is blocking stdio communication

Screenshots Fail

  • Ensure sufficient disk space in temp directory
  • Verify write permissions to system temp folder

OCR Fails / find_elements Returns Error

  • TESSDATA_PREFIX must point to the directory that directly contains eng.traineddata (not its parent)

…(正文过长,页面只展示前面部分,完整内容见仓库)

常见问题

6 问
答案由本站依据条目字段整理,不引用上游原文
Ghost MCP F1b32c90 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

Ghost MCP F1b32c90 怎么在 Claude Desktop、Claude 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Ghost MCP F1b32c90 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Ghost MCP F1b32c90 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

Ghost MCP F1b32c90 支持哪些客户端?

资料标注支持 Claude Desktop、Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Ghost MCP F1b32c90 能提供哪些能力?

资料显示约 26 个工具;能力标签包括 Go、Claude、AI控制。具体工具清单以官方文档为准。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。