gnome-screencast-mcp

GNOME에서 화면을 녹화하며, 명령줄 또는 MCP를 통한 AI 에이전트로 제어합니다.

GNOME Shell 시스템 기본 녹화기(바로 가기 Ctrl+Alt+Shift+R의 기반인 org.gnome.Shell.Screencast D-Bus 인터페이스)를 사용합니다. ffmpeg, wf-recorder 또는 어떤 외부 캡처 바이너리에도 의존하지 않습니다.

용도

그래픽 인터페이스를 건드리지 않고 화면 녹화를 자동화합니다: 데모, 버그 재현, 흐름 문서화, 테스트 세션 기록. 모든 명령이 JSON을 반환하므로 스크립트와 현재 작업을 녹화해야 하는 에이전트 모두에 적합합니다.

이 도구가 해결하는 문제: GNOME D-Bus를 직접 호출해서는 녹화가 작동하지 않습니다. 셸은 녹화를 시작한 D-Bus 클라이언트가 버스에서 떠나면 녹화를 종료하므로, 단독 gdbus call은 단일 프레임과 0:00 길이의 파일을 만들어냅니다. 여기서는 녹화가 끝날 때까지 연결을 유지하고 stop에서 깔끔하게 종료하는 보조 프로세스를 사용합니다. 그래야만 WebM이 올바른 길이와 인덱스로 만들어짐니다.

Related MCP server: video-capture-mcp

설치

복제하거나 컴파일할 것이 없습니다. 처음부터 첫 녹화까지 네 단계입니다.

아직 PyPI에 없습니다. 지금은 uv가 이 GitHub 저장소에서 직접 설치합니다 — 똑같이 작동하며 명령만 조금 더 길 뿐입니다. PyPI에 등록되면 gnome-screencast-mcp만으로 충분합니다. 두 가지는 서로 바꿔 쓸 수 있습니다.

1단계 — 요구 사항 확인

세 가지가 오류 없이 통과하면 2단계로 진행하세요.

2단계 — 설치

uv tool install --from git+https://github.com/quinho981/gnome-screencast-mcp gnome-screencast-mcp

셋이 PATH에 세 개의 실행 파일을 추가합니다:

터미널에서 설치 디렉터리가 PATH에 없다고 알려준다면, 터미널이 제안한 명령(보통 uv tool update-shell)을 실행하고 새 터미널을 엽니다.

3단계 — 테스트

gnome-screencast-start && sleep 3 && gnome-screencast-stop

"status": "recording" JSON, 3초 일시정지, "status": "stopped"와 duration_seconds가 3에 가까운 JSON이 출력되어야 합니다. 그렇게 나오면 모두 정상 — .webm 파일이 비디오 디렉터리에 있습니다.

문제가 생겼나요?바로 문제 해결로 이동하세요.

4단계 — 사용 방법 선택

• 명령줄로: 이미 준비되어 있습니다 — -o, -f, -a 옵션은 명령줄 사용법을 참고하세요.

• AI 에이전트(Claude Code, Cursor, opencode 등)로: 클라이언트에 MCP 서버를 등록해야 합니다 — 각각의 단계별 절차는 MCP 사용법을 참고하세요.

단계 없음: 에이전트에서 MCP만 작동시키려는 경우

사용 목적이 MCP뿐이라면 손으로 설치할 것이 없습니다 — 클라이언트가 실행할 때 스스로 패키지를 내려받습니다. 1단계의 요구 사항을 확인하고, 2단계와 3단계를 건너뛰고, 곧장 MCP 사용법으로 이동하세요.

자체 프로젝트에서 개발하려는 경우

이 저장소를 직접 수정할 분만 해당합니다:

git clone https://github.com/quinho981/gnome-screencast-mcp
cd gnome-screencast-mcp
uv run gnome-screencast-mcp        # servidor MCP a partir do código local
bash bin/start-recording.sh        # scripts de gravação, sem instalar nada
bash bin/stop-recording.sh

구조

스크립트는 bin/에 있어 클론에서 직접 사용할 수 있게 합니다. wheel 빌드가 이를 패키지 안으로 복사하며, 서버는 두 위치에서 모두 찾습니다.

명령줄 사용법

# Tela inteira, 30 fps, arquivo com data e hora em ~/Vídeos
gnome-screencast-start

# ... faça o que precisa ser gravado ...

gnome-screencast-stop

클론에서 bash bin/start-recording.sh와 bash bin/stop-recording.sh를 사용하면 됩니다.

start는 녹화가 시작되는 즉시 파일 경로를 반환합니다:

{
  "status": "recording",
  "file": "/home/user/Vídeos/screencast-20260824-152940.webm",
  "mode": "screen",
  "framerate": 30,
  "draw_cursor": true,
  "started_at": "2026-08-24T15:29:40-0300",
  "pid": 183615
}

stop는 녹화 요약을 반환합니다:

{
  "status": "stopped",
  "file": "/home/user/Vídeos/screencast-20260824-152940.webm",
  "size_bytes": 361637,
  "duration_seconds": 4.488
}

start 옵션

예 — 북서쪽 위 모서리, 1280×720, 60 fps, 커서 없음:

gnome-screencast-start -a 0 0 1280 720 -f 60 --no-cursor -o /tmp/demo.webm

stop 옵션

종료 코드

두 명령 모두 성공은 0, 사용 또는 환경 오류는 1을 반환합니다. 추가로:

• start: 2 이미 진행 중인 녹화가 있음 · 3 GNOME Shell이 녹화 시작을 거부함

• stop: 2 진행 중인 녹화가 없음 · 3 파일이 제 시간 안에 완성되지 못함

MCP 사용법

서버를 등록하면 녹화가 에이전트의 기능이 됩니다. 에이전트는 셸 접근권 없이 start_recording과 stop_recording을 타입 있는 도구로 호출합니다.

노출된 도구

recording_status는 동작하기 전에 값을 확인하는 저렴한 방법입니다 — 이미 있는 녹화를 시작하거나, 없는데 끝내려는 것을 피하게 합니다.

어느 클라이언트에서든 같은 명령

서버는 평범한 stdio 프로세스이며 명령은 어디서나 같습니다:

comando:    uvx
argumentos: gnome-screencast-mcp

uv tool install을 사용했다면 명령은 인수 없는 gnome-screencast-mcp 하나입니다.

패키지가 PyPI에 없을 때에는 아래 모든 예시에서 ["gnome-screencast-mcp"] 대신 이 인수 목록을 사용하세요:

["--from", "git+https://github.com/quinho981/gnome-screencast-mcp", "gnome-screencast-mcp"]

패키지가 배포되는 즉시 짧은 형식으로 돌아가면 됩니다 — 예시는 이미 짧은 형식으로 작성되었습니다.

정상적으로 보이는 구성을 부수는 두 가지가 있습니다:

1. uvx가 클라이언트 PATH에 없을 수 있음. Cursor, VS Code, Zed, Claude Desktop 같은 그래픽 런처에서 시작한 클라이언트는 보통 ~/.local/bin 없이 최약 PATH가 없습니다. 서버가 uvx: command not found로 실패한다면, uvx를 command -v uvx의 출력으로 대체하세요 — 주로 /home/<seu-usuário-no-sistema>에서 표시되는 /home/...은 ~/.local/bin/uvx아닙니다.

2. 녹화에는 세션 버스가 필요합니다. GNOME D-Bus는 DBUS_SESSION_BUS_ADDRESS와 XDG_RUNTIME_DIR 통해 연결됩니다. 그래픽 세션에서 시작한 클라이언트는 상속받지만, 컨테이너·snap·flatpak·SSH 세션에서는 그렇지 않습니다. 그 경우 서버의 env 블록에 두 변수를 선언하세요:

   "env": {
     "DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/1000/bus",
     "XDG_RUNTIME_DIR": "/run/user/1000"
   }

   시스템의 올바른 값은 그래픽 세션 터미널에서 echo $DBUS_SESSION_BUS_ADDRESS $XDG_RUNTIME_DIR로 확인하세요.

Claude Code

claude mcp add screen-recorder --scope user \
  -- uvx --from git+https://github.com/quinho981/gnome-screencast-mcp gnome-screencast-mcp

PyPI에 배포하면 -- uvx gnome-screencast-mcp로 줄어듭니다.

세션을 다시 시작하고 /mcp에서 screen-recorder가 connected로 뜨는지 확인하세요.

이 저장소 내에서는 그럴 필요도 없습니다: 저장소에 있는 .mcp.json이 로컬 코드로 서버를 미리 등록해 두므로, 프로젝트를 열 때 승인만 하면 됩니다.

Codex CLI

codex mcp add screen-recorder \
  -- uvx --from git+https://github.com/quinho981/gnome-screencast-mcp gnome-screencast-mcp

PyPI 출시 후에는 -- uvx gnome-screencast-mcp로 됩니다.

또는 직접 ~/.codex/config.toml:

[mcp_servers.screen-recorder]
command = "uvx"
args = ["gnome-screencast-mcp"]

opencode

프로젝트 루트의 opencode.json에, 또는 모든 프로젝트에 적용하려면 ~/.config/opencode/opencode.json에:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "screen-recorder": {
      "type": "local",
      "enabled": true,
      "command": ["gnome-screencast-mcp"]
    }
  }
}

이 방식은 설치 2단계의 uv tool install을 전제로 합니다. 명령은 실행 파일 이름만 있으며, PATH에서 이미 찾을 수 있습니다. opencode는 서버를 command로 지정한 방식만 사용합니다. However, Yod : failure if command does not take over from the start, and uvx gnome-screencast-mcp falls on in this case 업 패키지가 PyPI에 없으면 : each call would try to resolve and fail. If you prefer not to install it at all, the way that works without installing is the same as the uvx note (above) from other clients:

"command": ["uvx", "--from", "git+https://github.com/quinho981/gnome-screencast-mcp", "gnome-screencast-mcp"]

opencode는 커맨드가 command와 args로 나뉘지 않고 하나의 리스트로 들어가는 유일한 클라이언트입니다.

Cursor

~/.cursor/mcp.json(전역) 또는 .cursor/mcp.json(프로젝트 전용):

{
  "mcpServers": {
    "screen-recorder": {
      "command": "uvx",
      "args": ["gnome-screencast-mcp"]
    }
  }
}

Cursor는 그래픽 환경에서 시작합니다 — 연결이 안 되면 가장 가능성은 PATH에 uvx가 없는 것입니다. 어떤-등 암? 어느 클라이언트에서도 동일한 명령의 1번을 참조하세요.

Gemini CLI

gemini mcp add screen-recorder \
  uvx --from git+https://github.com/quinho981/gnome-screencast-mcp gnome-screencast-mcp

PyPI에 배포 후에는 uvx gnome-screencast-mcp로 줄입니다.

또는 직접 ~/.gemini/settings.json(전역) 또는 .gemini/settings.json(프로젝트 전용) — Cursor에 본 것과 같은 mcpServers 형식입니다.

VS Code (GitHub Copilot)

프로젝트에 .vscode/mcp.json에 있습니다. 키는 mcpServers가 아니라 servers이고, 타입을 명시해야 합니다:

{
  "servers": {
    "screen-recorder": {
      "type": "stdio",
      "command": "uvx",
      "args": ["gnome-screencast-mcp"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json에, Cursor와 개도포로 다른 mcpServers 형식으로 작성합니다.

Zed

Zed의 settings.json에서 context_servers 아래에:

{
  "context_servers": {
    "screen-recorder": {
      "source": "custom",
      "command": "uvx",
      "args": ["gnome-screencast-mcp"],
      "env": {}
    }
  }
}

Claude Desktop

Linux에서는 ~/.config/Claude/claude_desktop_config.json에, mcpServers 형식은 Cursor와 같습니다. 편집 후 앱을 완전히 다시 시작해야 합니다.

그 외 클라이언트

목록에 없는 클라이언트는 해당 문서에서 "MCP servers" 위치를 확인하고, uvx 명령에 인수 gnome-screencast-mcp를 넣어 지정하세요. 실제로 생태계에는 형식 두 가지만 있습니다: command와 args를 분리하는 방식(대부분)과 command가 단일 목록인 방식(opencode).

uv 없이

uv 없이

이 패키지는 일반적인 Python 프로젝트이며 pip로 충분합니다:

pip install --user git+https://github.com/quinho981/gnome-screencast-mcp

(PyPI에 게시한 뒤: pip install --user gnome-screencast-mcp.)

클라이언트에서 사용하는 명령어는 인수 없이 gnome-screencast-mcp가 됩니다. 전용 가상 환경도 잘 동작합니다. 그 경우에는 그 안의 실행 파일을 가리키면 됩니다. 서버는 스크립트에 전달하는 PATH에서 자신의 venv를 제거하므로, 스크립트는 계속 시스템의 PyGObject를 찾습니다.

클라이언트 없이 서버 테스트하기

에이전트 설정을 고민하기 전에, 서버가 제대로 뜨는지 확인해 둘 가치가 있습니다:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | uvx --from git+https://github.com/quinho981/gnome-screencast-mcp gnome-screencast-mcp

(PyPI에 게시한 뒤에는 uvx gnome-screencast-mcp만으로도 충분합니다.)

initialize의 응답이 출력되고, 이어서 세 가지 도구가 나와야 합니다. 첫 실행 때 uvx는 stderr에 설치 관련 줄도 함께 출력합니다.

동작 방식

start-recording.sh
  └─ setsid recorder-daemon.py        (sobrevive ao script que o criou)
       ├─ D-Bus: Screencast(...)      → o GNOME Shell começa a gravar
       ├─ escreve o estado em $XDG_RUNTIME_DIR/screen-recorder/current.json
       └─ fica vivo, segurando a conexão, até receber SIGTERM

stop-recording.sh
  └─ SIGTERM no pid do estado
       └─ daemon: D-Bus StopScreencast pela mesma conexão
            └─ espera o GStreamer fechar o WebM e escreve o resumo final

상태 파일은 한 번에 하나의 녹화만 존재하도록 보장합니다. 이는 동시에 하나의 screencast 세션만 지원하는 GNOME Shell 자체의 제한입니다.

데몬이 정리하지 않고 죽으면(예: 로그아웃) 상태 파일이 고아로 남습니다. recording_status가 stale을 나타내면, 다음 start_recording이 그 파일을 스스로 제거합니다.

구현 세부 사항

패키지가 우회해야 하는 함정은 세 가지입니다.

• 출력 캡처. 서버는 스크립트 실행 시 출력을 파이프가 아닌 임시 파일로 리디렉션합니다. 데몬은 출력 디스크립터를 상속하므로, 파이프는 녹화가 끝나야 EOF를 보게 되고, start_recording 호출도 그때까지 블로킹됩니다.

• Python 환경. 설치된 서버는 PATH의 맨 앞에 있는 가상 환경 안에서 실행됩니다. 그대로 두면 스크립트가 python3을 그 환경에서 찾게 되는데, 그 환경에는 시스템 PyGObject가 없습니다. 서버는 스크립트가 상속받는 환경에서 venv를 제거합니다.

• 실행 비트. 스크립트는 bash script.sh로, 데몬은 python3 daemon.py로 실행되며, 직접 호출되지 않습니다. 실행 권한은 wheel로 패키징했을 때 안정적으로 유지되지 않습니다.

자주 발생하는 문제

PyGObject não encontrado — sudo apt install python3-gi로 설치하세요. 명령줄에서는 나타나지 않고 MCP를 쓸 때만 나타난다면, venv가 스크립트의 PATH로 새어 나가고 있는 것입니다.

에이전트가 도구를 나열하지 않습니다 — 서버가 아예 뜨지 못한 경우입니다. 클라이언트 없이 서버 테스트하기의 테스트를 실행해 보세요. 그 테스트가 통과하면 문제는 클라이언트 설정에 있으며, 거의 항상 PATH 밖에 있는 uvx가 원인입니다(어느 클라이언트에서든 명령어의 1번 항목).

o **— 대개 접근 가능한 GNOME 세션이 없는 경우입니다. MCP 서버는 서버를 시작한 쪽의 환경을 상속하므로, D-Bus에는 DBUS_SESSION_BUS_ADDRESS와 XDG_RUNTIME_DIR이 필요합니다. MCP 클라이언트가 제한 환경(컨테이너, snap, flatpak, 서비스, SSH)에서 실행된다면, 로컬 서버의 env 블록에 두 변수를 선언하세요 — 어느 클라이언트에서든 명령어의 2번 항목을 참고하세요.

gravação já em andamento — stop_recording 또는 gnome-screencast-stop을 호출하세요. 상태를 직접 살펴보려면: cat $XDG_RUNTIME_DIR/screen-recorder/current.json.

재생 시간이 0:00인 영상 — 녹화가 이 명령들 밖에서 시작되었거나, 사용된 D-Bus 클라이언트가 살아남지 못했다는 뜻입니다. gnome-screencast-start를 사용하세요.

보조 프로세스 로그: $XDG_RUNTIME_DIR/screen-recorder/daemon.log.

라이선스

MIT — LICENSE를 참고하세요.

버전 발행

uv build          # gera dist/*.whl e dist/*.tar.gz
uv publish        # envia ao PyPI

버전은 pyproject.toml에 있습니다.