screen-mcp

Omarchy / Hyprland Wayland 데스크톱에서 AI 에이전트에 눈을 부여하는 MCP(Model Context Protocol) 서버입니다. grim을 통해 스크린샷을 캡처하고 Gemini API 기반의 선택적 이미지 분석을 제공합니다 — 호출하는 모델에 네이티브 비전 인코더가 없을 때 유용합니다.

기능

스크린샷은 grim(wlroots screencopy 프로토콜)을 사용합니다. X11은 필요하지 않습니다.

사전 요구 사항

• Omarchy, Hyprland 또는 wlroots 기반 Wayland 컴포지터

• grim — Wayland 스크린샷 도구

• slurp — (선택 사항) 대화형 영역 선택 도우미

• hyprctl — Hyprland 창/조회 CLI

• jq — (선택 사항) 일부 도우미 스크립트에서 사용

다음으로 확인합니다:

grim --help && hyprctl clients -j | head -c 20

이미지 분석용 (선택 사항)

• Gemini API 키 — https://aistudio.google.com에서 가져오기

• 환경에 내보냅니다:

export GEMINI_API_KEY="your-api-key-here"

키가 없어도 스크린샷 도구는 여전히 작동합니다. analyze_image와 screenshot_and_analyze만 오류를 반환합니다.

설치

Claude Desktop을 통해

Claude Desktop의 claude_desktop_config.json에 다음을 추가합니다:

{
  "mcpServers": {
    "screen-mcp": {
      "command": "npx",
      "args": ["-y", "screen-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

npx를 통해

npx -y screen-mcp

# Or install globally:
npm install -g screen-mcp

사용 예제

화면 영역 캡처

screenshot_region(x=100, y=200, width=800, height=600, include_cursor=true)

특정 창 캡처

먼저 사용 가능한 창을 나열하여 주소 또는 제목을 확인합니다:

list_windows()

그런 다음 제목(부분 일치), 주소 또는 "focused"로 캡처합니다:

screenshot_window(window="Spotify")
screenshot_window(window="focused")
screenshot_window(window="0x557ba79b4900")

Gemini로 이미지 분석

analyze_image(
  image_path="/tmp/my-screenshot.png",
  prompt="What applications are visible in this screenshot?",
  model="gemini-2.5-flash"
)

또는 base64로 인코딩된 이미지 데이터를 직접 전달합니다:

analyze_image(
  image="<base64-encoded-image>",
  prompt="Describe what you see in this image.",
  mime_type="image/png"
)

한 번에 캡처하고 분석

screenshot_and_analyze(
  x=0, y=0, width=1920, height=1080,
  prompt="Count the number of windows open and list their titles.",
  scale=0.5,
  model="gemini-2.5-flash"
)

개발

# Install deps
npm install

# Build
npm run build

# Run
npm start

# Development (recompile on change)
npm run dev

작동 방식

• 캡처: src/capture.ts는 grim(스크린샷)과 hyprctl(창 열거)을 래핑합니다. 창 캡처는 먼저 grim -T <stableId>(foreign-toplevel 핸들)을 시도하고, grim -g "<x>,<y> <w>x<h>"(hyprctl의 지오메트리)로 폴백합니다.

• 분석: src/gemini.ts는 공식 @google/genai SDK를 사용합니다. 이미지는 Gemini API의 interactions.create 엔드포인트에 base64 인라인으로 전달됩니다.

• 서버: src/index.ts는 @modelcontextprotocol/server를 사용하여 모든 것을 stdio 전송 MCP 서버로 연결합니다.

라이선스

MIT