Snipaya

snipaya-mcp

stdio に対応した任意の MCP クライアントを、macOS 用の画像・スクリーンショット注釈ツールである Snipaya に接続できます。アシスタントはキャンバスを読み取り、矢印、テキスト、図形、吹き出しを追加したり、機密データをマスキングしたり、切り抜きや書き出しをしたりできます。結果は Snipaya で確認できます。

Snipaya には、Streamable HTTP を使って 127.0.0.1 で提供される MCP サーバーが組み込まれています。snipaya-mcp は、ローカルの stdio サーバーしか起動できないクライアント向けの軽量なブリッジです。クライアントと Snipaya の間で、すべての MCP メッセージを変更せずに転送します。

Snipaya を開く前でも、ツールとプロンプトは一覧表示されます。Snipaya から応答があるまでは、ブリッジが組み込みカタログからそれらを一覧表示し、ツール呼び出しには次に行う操作を示すメッセージを返します。

MCP Registry では io.github.krzysztofsurdy/snipaya-mcp として、Glama および TensorBlock awesome-mcp-servers に掲載されています。

要件

• macOS 用の Snipaya。14 日間の無料トライアルが付属しています。
• Node.js 20 以降（npx でセットアップする場合）。

Snipaya で MCP サーバーを有効にする

サーバーはデフォルトでオフになっています。

1. Snipaya を開き、Settings > AI Assistants に移動します。
2. Allow AI assistants をオンにします。ステータスが Running に変わります。

ブリッジに必要な操作はこれだけです。この Mac 上で Snipaya が保存した設定からアクセストークンとポートを読み取るため、手動でコピーする必要はありません。

セットアップ

npx

npx -y snipaya-mcp

Snipaya が起動していなくても Allow AI assistants がオンであれば、ブリッジは Snipaya をバックグラウンドで開き、サーバーが起動するまで最大 10 秒待機します。

Snipaya に保存された設定を上書きするには、以下の変数またはフラグを設定します。フラグは変数より優先され、変数は保存済みの設定より優先されます。

変数	フラグ	デフォルト
SNIPAYA_MCP_TOKEN	--token	Snipaya が保存したトークン	Settings > AI Assistants のアクセストークン。
SNIPAYA_MCP_URL	--url	http://127.0.0.1:<saved port>/mcp、それ以外は http://127.0.0.1:47321/mcp	Snipaya のサーバー URL。127.0.0.1 と localhost のみ使用できます。
SNIPAYA_MCP_NO_LAUNCH			Snipaya を起動しない場合は 1 に設定します。Snipaya が閉じている間、ツール呼び出しは Cannot reach Snipaya を返します。

--token より環境変数を優先してください。コマンドラインフラグは、Mac 上のほかのプロセスから見えるためです。

JSON 設定

mcpServers JSON ファイルで設定するクライアントの場合：

{
  "mcpServers": {
    "snipaya": {
      "command": "npx",
      "args": ["-y", "snipaya-mcp"],
      "env": {
        "npm_config_registry": "https://registry.npmjs.org/"
      }
    }
  }
}

カスタム設定では、代わりに値を env に渡します。

{
  "mcpServers": {
    "snipaya": {
      "command": "npx",
      "args": ["-y", "snipaya-mcp"],
      "env": {
        "npm_config_registry": "https://registry.npmjs.org/",
        "SNIPAYA_MCP_TOKEN": "<access token>",
        "SNIPAYA_MCP_URL": "<server url>"
      }
    }
  }
}

クライアントが Streamable HTTP サーバーを直接サポートしている場合、このブリッジは不要です。代わりに Snipaya の Copy MCP config を使用してください。

MCP Bundle (.mcpb)

1. 最新リリースからsnipaya-mcp-<version>.mcpbをダウンロードします。
2. MCP Bundle に対応した MCP クライアントで開くか、クライアントの拡張機能設定にドラッグします。
3. Snipaya に保存された設定を使う場合はトークンと URL を空欄のままにします。独自の設定を使う場合は、Settings > AI Assistantsの値を貼り付けます。

セキュリティモデル

• ローカルのみ。 Snipaya のサーバーは127.0.0.1で待ち受け、ループバックのHostヘッダーとOriginヘッダーのないリクエストのみを受け付けるため、ブラウザー上のウェブサイトからアクセスすることはできません。ブリッジはホストが127.0.0.1またはlocalhost以外の URL を拒否し、Originヘッダーを送信しません。
• デフォルトでは無効。 Allow AI assistantsを有効にするまで、待ち受けは行われません。
• トークン。 すべてのリクエストにAuthorization: Bearer <token>が含まれます。トークンは Snipaya が生成し、Settings のRegenerateを使うと古いトークンは無効になります。ブリッジがトークンをログに書き込むことはありません。
• 保存済みの設定。 SNIPAYA_MCP_TOKENが設定されていない場合、ブリッジは~/Library/Application Support/Snipaya/mcp.jsonからトークンとポートを読み取ります。このファイルは Snipaya によって、macOS のユーザーのみが読み取れるように書き込まれます。ブリッジがこのファイルに書き込むことはありません。
• Snipaya の起動。 macOS でAllow AI assistantsが有効な場合に限り、ブリッジはまずトークンなしでリクエストを1回送り、Snipaya から応答があるか確認します。接続が拒否された場合は、open -g -b dev.snipaya.app（シェルは使用しません）を実行して再試行します。これは起動時、および Snipaya に接続できない状態でツール呼び出しがあった場合に行われます。トークンが拒否された場合など、その他の失敗時にアプリが起動することはありません。SNIPAYA_MCP_NO_LAUNCH=1を設定すると、この動作を無効にできます。
• ブリッジは転送のみを行います。 ブリッジ自体はツールを実行せず、何も保存せず、Snipaya にのみ接続します。Snipaya に接続できない間は、パッケージに同梱されたカタログからツールとプロンプトの一覧を返します。すべての操作は Snipaya 内で実行され、接続中のアシスタントと最近のアクティビティはSettings > AI Assistantsに表示されます。

ツール

ツールはインストール済みの Snipaya のバージョンによって異なります。Snipaya から応答があるまでは、ブリッジはカタログに含まれる Snipaya 1.3.3 のツールを一覧表示します。Snipaya から応答があった後は、インストール済みのバージョンのツール一覧が適用されます。Snipaya 1.3 では次のツールを利用できます。

Tool	Title
snipaya_get_canvas	キャンバスを取得
snipaya_render	キャンバスをレンダリング
snipaya_add_image	画像を追加
snipaya_add_arrow	矢印または線を追加
snipaya_add_shape	図形を追加
snipaya_add_text	テキストを追加
snipaya_add_step	ステップ番号を追加
snipaya_add_emoji	絵文字を追加
snipaya_add_freehand	フリーハンドの線を追加
snipaya_add_magnifier	拡大鏡を追加
snipaya_add_callout	吹き出しを追加
snipaya_add_spotlight	スポットライトを追加
snipaya_add_measure	寸法を追加
snipaya_pick_color	色を選択
snipaya_read_text	テキストを読み取る
snipaya_redact	機密データをマスキング
snipaya_update_items	要素を更新
snipaya_delete_items	要素を削除
snipaya_select	要素を選択
snipaya_arrange	画像を配置
snipaya_set_crop	トリミング範囲を設定
snipaya_undo	元に戻す
snipaya_redo	やり直す
snipaya_tabs	タブを管理
snipaya_export	画像をエクスポート
snipaya_list_destinations	エクスポート先を一覧表示
snipaya_export_to	エクスポート先にエクスポート
snipaya_save_project	プロジェクトを保存

プロンプト

Prompt	Title	Optional argument
explain_bug	スクリーンショット内のバグを説明	issue
redact_before_sharing	共有前に秘密情報をマスキング	also_hide
finish_screenshot	スクリーンショットを仕上げる	background
copy_text	画像からテキストをコピー	area
make_walkthrough	スクリーンショットから手順ガイドを作成	topic
compare_before_after	変更前と変更後を比較	change

トラブルシューティング

ブリッジは問題を stderr に出力します（プロトコルを伝送する stdout には出力しません）。Snipaya に接続できない間もツールの一覧は表示され、各ツール呼び出しの結果として同じテキストを返します。たとえば Snipaya を開いたり、使用許諾契約に同意したりして Snipaya が応答を開始すると、次のツール呼び出しで再起動せずに接続できます。

メッセージ	対処方法
Snipaya's settings were not found	Snipaya をインストールして一度開き、Allow AI assistants をオンにしてください。または SNIPAYA_MCP_TOKEN を設定してください。
Snipaya is a macOS app	ブリッジが別のシステムで実行されています。ツールの一覧は表示されますが、Mac 上の Snipaya でのみ使用できます。
Snipaya's MCP server is off	Settings > AI Assistants で Allow AI assistants をオンにしてください。
Snipaya's settings ... cannot be read または hold no valid token	Snipaya を開いて設定を書き直してから、Allow AI assistants を確認してください。または SNIPAYA_MCP_TOKEN を設定してください。
Cannot open Snipaya	macOS が見つけられる場所に Snipaya がインストールされていません。snipaya.app からインストールするか、自分で開いてください。
Opened Snipaya, but its MCP server starts only after you accept the license agreement	Snipaya 1.1 以降では、使用許諾契約に同意した後にのみ MCP サーバーが起動します。Snipaya のウィンドウで同意してから、もう一度ツールを呼び出してください。
Opened Snipaya, but its MCP server did not answer	Settings > AI Assistants を開き、ステータスの下に表示されているエラーを修正してください。
Cannot reach Snipaya at ...	Snipaya を開き、Allow AI assistants をオンにしてください。メッセージに使用許諾契約への言及がある場合は、先に Snipaya で同意してください。ステータスにエラーが表示されている場合は、先にそのエラーを修正してください。URL が Server URL と一致していることを確認してください。
Snipaya rejected the token	たとえば Regenerate の後などにトークンが変更されています。保存済みのトークンを使うには SNIPAYA_MCP_TOKEN を削除するか、現在のトークンをコピーしてください。
Snipaya ended the session	Snipaya が再起動したか、トークンが変更されました。クライアントで snipaya サーバーを再起動してください。
Refusing <host>	URL は 127.0.0.1 または localhost を指定する必要があります。Snipaya から Server URL をコピーしてください。
CONNECTION_CLOSED または Failed to connect が表示され、MCP ログに npm error 404 ... is not in this registry がある	ブリッジが起動していません。プロジェクトの .npmrc により npm の参照先がプライベートレジストリになっています。MCP クライアントはプロジェクトフォルダーでサーバーを起動します。上記の JSON 設定例のように、env で snipaya サーバーの npm_config_registry を https://registry.npmjs.org/ に設定してください。Claude Code では、プロジェクトごとに claude mcp add --scope user snipaya -e npm_config_registry=https://registry.npmjs.org/ -- npx -y snipaya-mcp を使ってサーバーを追加してください。Claude Code は MCP サーバーのログを ~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-snipaya/ に保存します。

npx -y snipaya-mcp --help を実行すると、オプションを確認できます。

開発

npm ci
npm run lint
npm run typecheck
npm test          # builds, then runs the bridge over stdio against a local test server
npm run pack:mcpb # builds snipaya-mcp-<version>.mcpb with the official mcpb CLI

カタログ

catalog.json には、Snipaya に接続できない間にブリッジが提供するツール、プロンプト、手順が格納されており、manifest.json には同じツールとプロンプトが記載されています。Snipaya アプリのチェックアウト（デフォルトは ../snipaya）から Node 22.6 以降を使って両方を再生成し、結果をコミットしてください。

npm run sync:catalog -- ../snipaya

トークンも URL も指定されていない場合、ブリッジはインストール済みの Snipaya の設定を ~/Library/Application Support/Snipaya から読み取ります。Snipaya の開発ビルドは専用の Snipaya Dev プロファイルフォルダーに設定を保存するため、開発ビルドに接続するには、Settings > AI Assistants に表示される値を SNIPAYA_MCP_TOKEN と SNIPAYA_MCP_URL に設定してください。

リリース

v* タグをプッシュすると .github/workflows/release.yml が実行されます。CI チェックを実行し、タグが package.json、package-lock.json、server.json、manifest.json のバージョンと一致することを確認したうえで、npm にバージョンをステージングし（provenance 付き）、メンテナーが承認するまで最大 60 分待機します。その後、.mcpb を添付して GitHub リリースを作成し、server.json を MCP Registry に公開します。

初回セットアップ

npmjs.com で snipaya-mcp > Settings > Trusted publishing を開き、GitHub Actions を選択して、次の内容を入力します。

項目	値
Organization or user	krzysztofsurdy
Repository	snipaya-mcp
Workflow filename	release.yml
Environment name	空欄のままにします
Allowed actions	npm stage publish のみ

npm では、2 日以内に公開されていない信頼されたパブリッシャーは期限切れになるため、初回リリースの直前に追加してください。MCP Registry と GitHub リリースのセットアップは不要です。ワークフロー自身の GitHub トークンを使用します。

リリースを作成する

npm version minor        # or patch, major: bumps all four files, commits and tags v<version>
git push --follow-tags

ワークフローが Publish to npm に到達したら、2FA プロンプトでステージングされたバージョンを承認します：npm stage approve snipaya-mcp@<version>。または、npmjs.com のパッケージページから承認できます。残りのリリース処理は自動的に続行されます。

失敗したリリースを再実行しても安全です。該当バージョンがすでに公開されている場合、npm と MCP Registry への公開はスキップされ、既存の GitHub リリースのバンドルは置き換えられます。

ライセンス

MIT