Claude KVM

आधिकारिक

🤖 ⚡️ MCP सर्वर ( MacOS) — VNC के माध्यम से रिमोट डेस्कटॉप को नियंत्रित करें

दस्तावेज़

Claude KVM

दूरस्थ पहुँच, कृत्रिम बुद्धिमत्ता

Claude KVM एक MCP उपकरण है जो VNC के माध्यम से दूरस्थ डेस्कटॉप वातावरण को नियंत्रित करता है। इसमें एक पतली JS प्रॉक्सी परत (MCP सर्वर) और आपके macOS सिस्टम पर चलने वाला एक प्लेटफ़ॉर्म-नेटिव Swift VNC डेमॉन शामिल है।

[!TIP] Phantom-WG आपके लिए एक बढ़िया विकल्प हो सकता है। अपने VNC सर्वर को अपने नेटवर्क के भीतर पृथक करें और साथ ही स्व-होस्टेड VPN प्रदर्शन का आनंद लें, जिसमें आपको अतिरिक्त गोपनीयता सुविधाएँ भी मिलती हैं।

लाइव परीक्षण रन

[!NOTE] परीक्षण GitHub Actions पर पारदर्शी रूप से आयोजित किए जाते हैं — CI वातावरण में प्रत्येक चरण दिखाई देता है। प्रत्येक परीक्षण के अंत में, चाहे एकीकरण सफल हो या विफल, आपको सत्र के दौरान एजेंट द्वारा उठाए गए प्रत्येक कदम के स्क्रीनशॉट मिलेंगे, साथ ही एक .mp4 वीडियो रिकॉर्डिंग भी मिलेगी जो पूरे सत्र को कैप्चर करती है। इन रिकॉर्डिंग और स्क्रीनशॉट की समीक्षा करके, आप देख सकते हैं कि एजेंट प्रत्येक चरण में कैसे आगे बढ़ा, कार्य में कितना समय लगा, और सिस्टम प्रॉम्प्ट के आधार पर क्या निर्णय लिए गए। आप अपने स्वयं के वातावरण में MCP सर्वर के लिए अपने सिस्टम प्रॉम्प्ट या निर्देश तैयार करते समय इन उदाहरणों का संदर्भ के रूप में उपयोग कर सकते हैं।

[!WARNING] इन रन से जुड़ी कलाकृतियाँ GitHub की कलाकृति अवधारण नीति के कारण समाप्त हो सकती हैं। स्थायी प्रतियाँ Persist Artifacts वर्कफ़्लो के माध्यम से तैयार की जाती हैं और इन्हें हमेशा प्रेस-किट शाखा पर artifacts/ निर्देशिका से रन आईडी द्वारा एक्सेस किया जा सकता है।

आर्किटेक्चर

graph TB
    subgraph MCP["MCP Client (Claude)"]
        AI["Claude"]
    end

    subgraph Proxy["claude-kvm · MCP Proxy (stdio)"]
        direction TB
        Server["MCP Server<br/><code>index.js</code>"]
        Tools["Tool Definitions<br/><code>tools/index.js</code>"]
        Server --> Tools
    end

    subgraph Daemon["claude-kvm-daemon · Native VNC Client (stdin/stdout)"]
        direction TB
        CMD["Command Handler<br/><i>PC Dispatch</i>"]
        Scale["Display Scaling<br/><i>Scaled ↔ Native</i>"]

        subgraph Screen["Screen"]
            Capture["Frame Capture<br/><i>PNG · Crop · Diff</i>"]
            OCR["OCR Detection<br/><i>Apple Vision</i>"]
        end

        subgraph InputGroup["Input"]
            Mouse["Mouse<br/><i>Click · Drag · Move · Scroll</i>"]
            KB["Keyboard<br/><i>Tap · Combo · Type · Paste</i>"]
        end

        VNC["VNC Bridge<br/><i>LibVNCClient 0.9.15</i>"]

        CMD --> Scale
        Scale --> Capture
        Scale --> Mouse
        Scale --> KB
        Capture -.->|"framebuffer"| VNC
        Mouse -->|"pointer events"| VNC
        KB -->|"key events"| VNC
    end

    subgraph Target["Target Machine"]
        VNC_Server["VNC Server<br/><i>:5900</i>"]
        Desktop["Desktop Environment"]
        VNC_Server --> Desktop
    end

    AI <-->|"stdio<br/>JSON-RPC"| Server
    Server <-->|"stdin/stdout<br/>PC (NDJSON)"| CMD
    VNC <-->|"RFB Protocol<br/>TCP :5900"| VNC_Server

    classDef proxy fill:#1a1a2e,stroke:#16213e,color:#e5e5e5
    classDef daemon fill:#0f3460,stroke:#533483,color:#e5e5e5
    classDef target fill:#1a1a2e,stroke:#e94560,color:#e5e5e5

    class Server,Tools proxy
    class CMD,Scale,VNC,Capture,Mouse,KB daemon
    class VNC_Server,Desktop target

परतें

परत	भाषा	भूमिका	संचार
MCP प्रॉक्सी	JavaScript (Node.js)	MCP प्रोटोकॉल पर Claude के साथ संचार करता है, डेमॉन जीवनचक्र प्रबंधित करता है	stdio JSON-RPC
VNC डेमॉन	Swift/C (Apple Silicon)	VNC कनेक्शन, स्क्रीन कैप्चर, माउस/कीबोर्ड इनपुट इंजेक्शन	stdin/stdout PC (NDJSON)

PC (प्रक्रिया कॉल) प्रोटोकॉल

प्रॉक्सी और डेमॉन के बीच संचार NDJSON पर PC प्रोटोकॉल का उपयोग करता है:

Request:      {"method":"<name>","params":{...},"id":<int|string>}
Response:     {"result":{...},"id":<int|string>}
Error:        {"error":{"code":<int>,"message":"..."},"id":<int|string>}
Notification: {"method":"<name>","params":{...}}

समन्वय स्केलिंग

VNC सर्वर का मूल रिज़ॉल्यूशन --max-dimension (डिफ़ॉल्ट: 1280px) के भीतर फ़िट होने के लिए स्केल डाउन किया जाता है। Claude स्केल किए गए निर्देशांकों के साथ अधिक सुसंगत रूप से काम करता है — डेमॉन पृष्ठभूमि में रूपांतरण संभालता है:

Native:  4220 x 2568  (VNC server framebuffer)
Scaled:  1280 x 779   (what Claude sees and targets)

mouse_click(640, 400) → VNC receives (2110, 1284)

स्क्रीन रणनीति

Claude एक प्रगतिशील सत्यापन दृष्टिकोण के साथ टोकन लागत को कम करता है:

diff_check       →  changeDetected: true/false     ~5ms    (text only, no image)
detect_elements  →  OCR text + bounding boxes      ~50ms   (text only, no image)
cursor_crop      →  crop around cursor              ~50ms   (small image)
screenshot       →  full screen capture             ~200ms  (full image)

detect_elements ऑन-डिवाइस OCR के लिए Apple Vision फ्रेमवर्क का उपयोग करता है। स्केल किए गए स्थान में बाउंडिंग बॉक्स निर्देशांक के साथ टेक्स्ट सामग्री लौटाता है — विज़न टोकन का उपभोग किए बिना सटीक क्लिक लक्ष्यीकरण सक्षम करता है।

स्थापना

आवश्यकताएँ

macOS (Apple Silicon / aarch64)
Node.js (LTS)

डेमॉन

brew tap ARAS-Workspace/tap
brew install claude-kvm-daemon

[!NOTE] claude-kvm-daemon CI (GitHub Actions) के माध्यम से संकलित और कोड-हस्ताक्षरित है। बिल्ड आउटपुट दो स्वरूपों में पैक किया जाता है: Homebrew वितरण के लिए एक .tar.gz संग्रह और नोटरीकरण के लिए एक .dmg डिस्क छवि। DMG को उसी वर्कफ़्लो के भीतर नोटरीकरण के लिए Apple सर्वर पर सबमिट किया जाता है — प्रक्रिया को CI लॉग से ट्रैक किया जा सकता है। नोटरीकृत DMG एक CI कलाकृति के रूप में उपलब्ध है; संग्रहीत .tar.gz भी रिपॉजिटरी पर एक रिलीज़ के रूप में प्रकाशित किया जाता है। Homebrew स्थापना इस रिलीज़ को ट्रैक करती है।

रिलीज़ · स्रोत कोड

LibVNC बिल्ड · LibVNC शाखा

Homebrew टैप

MCP कॉन्फ़िगरेशन

अपनी परियोजना निर्देशिका में एक .mcp.json फ़ाइल बनाएँ:

{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"],
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_USERNAME": "user",
        "VNC_PASSWORD": "pass",
        "CLAUDE_KVM_DAEMON_PATH": "/opt/homebrew/bin/claude-kvm-daemon",
        "CLAUDE_KVM_DAEMON_PARAMETERS": "-v"
      }
    }
  }
}

[!NOTE] उपकरण का CI के माध्यम से एंड-टू-एंड परीक्षण किया जाता है — Claude VNC पर कार्य निष्पादित करता है जबकि एक स्वतंत्र विज़न मॉडल परिणामों का अवलोकन और सत्यापन करता है। लाइव वर्कफ़्लो रन, सिस्टम प्रॉम्प्ट और डेमो रिकॉर्डिंग के लिए एकीकरण परीक्षण देखें।

कॉन्फ़िगरेशन

MCP प्रॉक्सी (ENV)

पैरामीटर	डिफ़ॉल्ट	विवरण
`VNC_HOST`	`127.0.0.1`	VNC सर्वर पता
`VNC_PORT`	`5900`	VNC पोर्ट संख्या
`VNC_USERNAME`		उपयोगकर्ता नाम (ARD के लिए आवश्यक)
`VNC_PASSWORD`		पासवर्ड
`CLAUDE_KVM_DAEMON_PATH`	`claude-kvm-daemon`	डेमॉन बाइनरी पथ (यदि पहले से PATH में है तो आवश्यक नहीं)
`CLAUDE_KVM_DAEMON_PARAMETERS`		डेमॉन के लिए अतिरिक्त CLI तर्क

डेमॉन पैरामीटर (CLI)

CLAUDE_KVM_DAEMON_PARAMETERS के माध्यम से डेमॉन को दिए गए अतिरिक्त तर्क:

"CLAUDE_KVM_DAEMON_PARAMETERS": "--max-dimension 800 -v"

पैरामीटर	डिफ़ॉल्ट	विवरण
`--max-dimension`	`1280`	अधिकतम डिस्प्ले स्केलिंग आयाम (px)
`--connect-timeout`		VNC कनेक्शन टाइमआउट (सेकंड)
`--bits-per-sample`		बिट्स प्रति पिक्सेल नमूना
`--no-reconnect`		स्वचालित पुनः कनेक्शन अक्षम करें
`-v, --verbose`		वर्बोज़ लॉगिंग (stderr)

रनटाइम कॉन्फ़िगरेशन (PC)

सभी समय और प्रदर्शन पैरामीटर configure विधि के माध्यम से रनटाइम पर कॉन्फ़िगर करने योग्य हैं। वर्तमान मानों का निरीक्षण करने के लिए get_timing का उपयोग करें।

समय सेट करें:

{"method":"configure","params":{"click_hold_ms":80,"key_hold_ms":50}}

{"result":{"detail":"OK — changed: click_hold_ms, key_hold_ms"}}

डिस्प्ले स्केलिंग बदलें:

{"method":"configure","params":{"max_dimension":960}}

{"result":{"detail":"OK — changed: max_dimension","scaledWidth":960,"scaledHeight":584}}

डिफ़ॉल्ट पर रीसेट करें:

{"method":"configure","params":{"reset":true}}

{"result":{"detail":"OK — reset to defaults","timing":{"click_hold_ms":50,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":30,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}

वर्तमान मान प्राप्त करें:

{"method":"get_timing"}

{"result":{"timing":{"click_hold_ms":80,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":50,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}

पैरामीटर	डिफ़ॉल्ट	विवरण
`max_dimension`	`1280`	अधिकतम स्क्रीनशॉट आयाम
`cursor_crop_radius`	`150`	कर्सर क्रॉप त्रिज्या (px)
`click_hold_ms`	`50`	क्लिक होल्ड अवधि
`double_click_gap_ms`	`50`	डबल-क्लिक अंतराल विलंब
`hover_settle_ms`	`400`	होवर सेटल प्रतीक्षा
`drag_position_ms`	`30`	प्री-ड्रैग स्थिति प्रतीक्षा
`drag_press_ms`	`50`	ड्रैग प्रेस होल्ड सीमा
`drag_step_ms`	`5`	इंटरपोलेशन बिंदुओं के बीच
`drag_settle_ms`	`30`	रिलीज़ से पहले सेटल
`drag_pixels_per_step`	`20`	बिंदु घनत्व प्रति पिक्सेल
`drag_min_steps`	`10`	न्यूनतम इंटरपोलेशन चरण
`scroll_press_ms`	`10`	स्क्रॉल प्रेस-रिलीज़ अंतराल
`scroll_tick_ms`	`20`	इंटर-टिक विलंब
`key_hold_ms`	`30`	कुंजी होल्ड अवधि
`combo_mod_ms`	`10`	संशोधक सेटल विलंब
`type_key_ms`	`20`	टाइपिंग के दौरान कुंजी होल्ड
`type_inter_key_ms`	`20`	अंतर-वर्ण विलंब
`type_shift_ms`	`10`	शिफ़्ट कुंजी सेटल
`paste_settle_ms`	`30`	क्लिपबोर्ड लेखन के बाद प्रतीक्षा

उपकरण

सभी ऑपरेशन एकल vnc_command उपकरण के माध्यम से किए जाते हैं:

स्क्रीन

क्रिया	पैरामीटर	विवरण
`screenshot`		पूर्ण स्क्रीन PNG कैप्चर
`cursor_crop`		क्रॉसहेयर ओवरले के साथ कर्सर के चारों ओर क्रॉप
`diff_check`		बेसलाइन के विरुद्ध स्क्रीन परिवर्तनों का पता लगाएं
`set_baseline`		वर्तमान स्क्रीन को अंतर संदर्भ के रूप में सहेजें

माउस

क्रिया	पैरामीटर	विवरण
`mouse_click`	`x, y, button?`	क्लिक (बायाँ\|दायाँ\|मध्य)
`mouse_double_click`	`x, y`	डबल क्लिक
`mouse_move`	`x, y`	कर्सर ले जाएँ
`hover`	`x, y`	ले जाएँ + सेटल प्रतीक्षा
`nudge`	`dx, dy`	सापेक्ष कर्सर गति
`mouse_drag`	`x, y, toX, toY`	प्रारंभ से अंत तक खींचें
`scroll`	`x, y, direction, amount?`	स्क्रॉल (ऊपर\|नीचे\|बाएँ\|दाएँ)

कीबोर्ड

क्रिया	पैरामीटर	विवरण
`key_tap`	`key`	एकल कुंजी दबाव (enter\|escape\|tab\|space\|...)
`key_combo`	`key` या `keys`	संशोधक कॉम्बो ("cmd+c" या ["cmd","shift","3"])
`key_type`	`text`	वर्ण दर वर्ण टेक्स्ट टाइप करें
`paste`	`text`	क्लिपबोर्ड के माध्यम से टेक्स्ट चिपकाएँ

पहचान

क्रिया	पैरामीटर	विवरण
`detect_elements`		बाउंडिंग बॉक्स के साथ OCR टेक्स्ट पहचान (Apple Vision)

स्केल किए गए स्थान में बाउंडिंग बॉक्स निर्देशांक के साथ टेक्स्ट तत्व लौटाता है:

{"method":"detect_elements"}

{"result":{"detail":"13 elements","elements":[{"confidence":1,"h":9,"text":"Finder","w":32,"x":37,"y":6},{"confidence":1,"h":9,"text":"File","w":15,"x":84,"y":6},{"confidence":1,"h":9,"text":"Edit","w":19,"x":112,"y":6},{"confidence":1,"h":9,"text":"View","w":22,"x":143,"y":6},{"confidence":1,"h":11,"text":"Go","w":15,"x":179,"y":6},{"confidence":1,"h":9,"text":"Window","w":35,"x":207,"y":6},{"confidence":1,"h":11,"text":"Help","w":22,"x":255,"y":6},{"confidence":1,"h":11,"text":"8•","w":26,"x":1161,"y":6},{"confidence":1,"h":9,"text":"Fri Feb 20 22:19","w":80,"x":1189,"y":6},{"confidence":1,"h":9,"text":"Assets","w":32,"x":1202,"y":97},{"confidence":1,"h":9,"text":"Passwords.kdbx","w":74,"x":1181,"y":168},{"confidence":1,"h":93,"text":"PHANTOM","w":633,"x":322,"y":477},{"confidence":1,"h":32,"text":"YOUR SERVER, YOUR NETWORK, YOUR PRIVACY","w":629,"x":325,"y":568}],"scaledHeight":717,"scaledWidth":1280}}

कॉन्फ़िगरेशन

क्रिया	पैरामीटर	विवरण
`configure`	`{<params>}`	रनटाइम पर समय/प्रदर्शन पैरामीटर सेट करें
`configure`	`{reset: true}`	सभी पैरामीटर को डिफ़ॉल्ट पर रीसेट करें
`get_timing`		वर्तमान समय + प्रदर्शन पैरामीटर प्राप्त करें

नियंत्रण

क्रिया	पैरामीटर	विवरण
`wait`	`ms?`	प्रतीक्षा करें (डिफ़ॉल्ट 500ms)
`health`		कनेक्शन स्थिति + प्रदर्शन जानकारी
`shutdown`		सुचारू डेमॉन शटडाउन

प्रमाणीकरण

समर्थित VNC प्रमाणीकरण विधियाँ:

VNC Auth — पासवर्ड-आधारित चुनौती-प्रतिक्रिया (DES)
ARD — Apple रिमोट डेस्कटॉप (Diffie-Hellman + AES-128-ECB)

macOS का ARD प्रमाणीकरण प्रकार 30 क्रेडेंशियल अनुरोध के माध्यम से स्वतः पता लगाया जाता है। पता चलने पर, Meta कुंजियाँ Super (कमांड कुंजी संगतता) पर रीमैप की जाती हैं।

[!NOTE] बेयर-मेटल मैक पर चल रहा है? VNC सख्तीकरण, SSH टनलिंग, और सत्र स्थिरता युक्तियों के लिए Mac M1 तैयारी ट्रिक्स देखें।

"Claude" Anthropic, PBC का एक ट्रेडमार्क है। यह परियोजना Anthropic से संबद्ध या समर्थित नहीं है।