gnome-screencast-mcp

GNOME の画面録画をコマンドラインまたは AI エージェントから操作できるようにします。MCP 経由で利用します。

GNOME Shell 標準のレコーダー（D-Bus インターフェース org.gnome.Shell.Screencast。これは Ctrl+Alt+Shift+R のショートカットと同じものです）を使用します。ffmpeg や wf-recorder、またはその他の外部キャプチャバイナリには依存しません。

用途

グラフィカルインターフェースに触れずに画面録画を自動化します。デモ、バグの証拠、フローのドキュメント化作業、テストセッションの記録などに使えます。各コマンドが JSON を返すため、スクリプトでも、自分の作業内容を録画する必要がある AI エージェントでも利用できます。

このツールが解決する問題: GNOME の D-Bus を直接呼んでも、録画には対応していません。起動した D-Bus クライアントがバスから離れると、GNOME Shell はすぐに録画を終了します。そのため、単発の gdbus call では、1フレームと 0:00 の長さしかないファイルができます。このツールの補助プロセスが録画中ずっと接続を維持し、ストップ時にクリーンに終了することで、はじめて正しい長さとインデックスの WebM が生成されます。

Related MCP server: video-capture-mcp

インストール

クローンやビルドの必要はありません。ゼロから最初の録画まで、4つのステップだけです。

PyPI にはまだ公開されていません。 現時点では uv がこの GitHub リポジトリから直接インストールします。動作は同じで、コマンドが少し長いだけです。PyPI に公開されれば、gnome-screencast-mcp だけで十分になり、2つの形式を入れ替えて使えます。

ステップ 1 — 要件を確認する

3つが問題なく動作すれば、ステップ 2 に進んでください。

ステップ 2 — インストールする

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

これで 3 つの実行ファイルが PATH に追加されます。

ターミナルが、インストールディレクトリが PATH に含まれていないと警告した場合は、それが提案するコマンド（通常は uv tool update-shell）を実行し、新しいターミナルを開いてください。

ステップ 3 — テストする

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

JSON で "status": "recording" が出力され、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"]

PyPI に公開されたら、短い形式に戻してください。例はすでに短い形式で書かれています。

正しく見える設定を壊すものは2つあります:

1. uvx がクライアントの PATH にない場合。 グラフィカルなランチャーからの一覧 (Cursor、VS Code、Zed、Claude Desktop など) で起動されるクライアントは、通常、最小限の PATH を継承し、~/.local/bin は含まれません。サーバーで uvx: command not found が発生したら、uvx を command -v uvx の出力（通常は /home/<seu-usuário-do-sistema>/.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 が接続されていることを確認してください。

このリポジトリ内では、この操作すら必要ありません。ここにバージョン管理された .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 は、コマンドが最初から起動に失敗すると、サーバーを失敗とマークし（enabled も自動的に false に戻します）、uvx gnome-screencast-mcp は、PyPI にパッケージが無い間はこれに該当します。呼び出すたびに PyPI で解決しようとして失敗します。どうしてもインストールしたくない場合は、インストール不要で使える方法は、他のクライアントの git+ と同じ形です:

"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 で、かつ type が明示されていることに注意してください:

{
  "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 に、Cursor と同じ mcpServers 形式で設定します。編集後は、アプリを完全に再起動する必要があります。

その他のクライアント

お使いのクライアントが一覧にない場合は、そのクライアントのドキュメントで「MCP servers」の説明を確認し、uvx コマンドに引数 gnome-screencast-mcp を渡してください。実際には、エコシステム中でフォーマットは2つだけです。command と args を別々に持つもの（大部分）と、command を単一のリストとして持つもの（opencode）です。

uv がいない場合

The package is a standard Python project, and pip handles it:

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

(Once published to PyPI: pip install --user gnome-screencast-mcp.)

The client command becomes gnome-screencast-mcp, with no arguments. A dedicated virtual environment also works — in that case, the point to the executable inside it; the server removes its own venv from the PATH it passes to the scripts, so they keep finding the system PyGObject.

Testing the server without a client

Before wrestling with an agent's configuration, it's worth confirming the server comes up:

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

(Once published to PyPI, uvx gnome-screencast-mcp alone is enough.)

The initialize response should appear, followed by the three tools. On the first run, uvx also prints an installation line to stderr.

How it works

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

The state file ensures there is only one recording at a time — a limit of GNOME Shell itself, which supports one at a time simultaneous screencast session.

If the daemon dies without cleaning up (for example, on logout), the state file is left orphaned: recording_status reports stale and the next start_recording removes it by itself.

Implementation details

Three pitfalls the package needs to work around:

• Output capture. The server runs the scripts with output redirected to temporary files, not pipes. The daemon inherits the output descriptors, so a pipe would only see EOF at the end of the recording — and the start_recording call would hang until then.

• Python environment. Once installed, the server runs inside a virtual environment, which sits at the beginning of the PATH. The scripts would start resolving python3 to it, where the system PyGObject doesn't exist. The server removes the venv from the environment the scripts inherit.

• Executable bit. The scripts are invoked as bash script.sh and the daemon is invoked as python3 daemon.py, never directly: the execute permission doesn't survive reliably when packaged into a wheel.

Common problems

PyGObject not found — install with sudo apt install python3-gi. If the issue appears only when using the MCP server and not on the command line, the venv is leaking into the PATH of the scripts.

The agent does not list the tools — the server never even started. Run the test from to Testing the server without a client; if it passes, the problem is in the client configuration, almost always with uvx outside the PATH (item 1 of O comando, em qualquer cliente).

the GNOME Shell refused to start the recording — usually there is no accessible GNOME session. The MCP server inherits the environment from whoever started it, and D-Bus needs DBUS_SESSION_BUS_ADDRESS and XDG_RUNTIME_DIR. If the MCP and not on the command line, the venv is leaking into the PATH of the scripts; if it appears only at MCP server level, the client/client is in a confined environment (container, snap, flatpak, service, SSH), set both variables in the server env block — see item 2 of The command, in any client.

recording already in progress — call stop_recording, or gnome-screencast-stop. To inspect the state by hand: cat $XDG_RUNTIME_DIR/screen-recorder/current.json.

Video with a 0:00 duration — a sign that the recording was started outside these commands, with a D-Bus client that didn't survive. Use gnome-screencast-start.

Auxiliary process log: $XDG_RUNTIME_DIR/screen-recorder/daemon.log.

License

MIT — see LICENSE.

Publishing a version

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

The version is defined in pyproject.toml.