Swing MCP

swing-mcp

AI アシスタントで Java デスクトップアプリケーション（Swing と JavaFX）を操作できます。UI のスナップショットを取得し、クリックや入力、フォームへの記入、テーブルやツリーの読み取り、メニューやダイアログの操作が可能です。chrome-devtools-mcp に着想を得ていますが、HTML ページではなく、実行中の Java UI を対象としています。

ひと組のツールでどちらのツールキットも操作でき、両方を組み合わせたアプリケーションでは同時に操作できます。どちらを使っているかを指定する必要はありません。

ビジネスソフトウェアの多くは Java デスクトップソフトウェアです。社内ツール、ERP クライアント、POS、研究室や物流のシステムなどは、API も Web UI もなく、Swing、そして近年では JavaFX で書かれています。Swing MCP は、アプリケーション自体を変更することなく、Claude のようなアシスタントがインターフェースを確認して操作できる、安全で権限管理された窓口を提供し、こうしたソフトウェアを AI 時代へと導きます。

クイックスタート（Claude Desktop）

1. JDK 21+ が PATH に設定されていることを確認します。
2. 最新リリースから swing-mcp.mcpb をダウンロードします。
3. ファイルを開くと、Claude Desktop が拡張機能としてインストールします。
4. Claude にアプリケーションの launch_app を依頼します（または PID を指定して実行中のアプリケーションに attach_to_app します）。あとは Claude に任せましょう。

別の MCP クライアントをお使いですか？各クライアント向けのガイドと1分間の動画をご用意しています。Claude Code、VS Code + Copilot、Cursor、Devin Desktop（Windsurf）、IntelliJ IDEA、Codex CLI、Gemini CLIについては、docs/installation.md · 動画をご覧ください。より詳しい説明をご希望ですか？インストールから初回利用までを解説する3分間の動画をご覧ください。JavaFX アプリをお使いですか？実際の操作をご覧ください（96秒間、すべて実際の MCP ログに記録されたツール呼び出しです）。

ご自身のアプリケーションへの接続が必要な場合、または自社で運用している他のソフトウェア向けの MCP コネクターが必要な場合は、CrossTech が開発します：crosstech.solutions/swing-mcp。

モジュール

• swing-mcp-server — 自動化ツールを公開する Spring Boot MCP サーバー（stdio トランスポート）。
• swing-mcp-agent — 対象の JVM に読み込まれる Java エージェント（起動時に -javaagent を指定するか、PID を使って動的に読み込みます）。localhost 専用の JSON 行プロトコルソケットサーバーを実行します。サポート対象の各ツールキット用に UiToolkit 実装を備え、各コマンドを適切な実装に振り分けます。docs/adr/0001-multi-toolkit-agent.mdを参照してください。
• swing-mcp-common — コマンド／DTO 型と UiToolkit インターフェースを共有します。
• swing-mcp-demo — 統合テストに使用する Swing デモアプリケーション。
• swing-mcp-demo-fx — 統合テストに使用する JavaFX デモアプリケーション（ツールキット経由、および stdio 経由で実際のサーバーを介して操作します）。

仕組み

MCP client (stdio) ──▶ swing-mcp-server ──localhost socket──▶ swing-mcp-agent (inside target JVM) ──▶ Swing EDT
                                                                                         └──▶ JavaFX Application Thread

1. MCP クライアントが launch_app（エージェントを事前に読み込んだ状態で JVM を起動）または attach_to_app（PID を使って実行中の JVM にエージェントを読み込み）を呼び出します。
2. エージェントが swing.mcp.agent-port-min..max の範囲内でループバック限定のポートにバインドし、レスポンスファイルを通じてそのポートを返します。
3. take_snapshot、click、fill などのツールは JSON 行コマンドとして転送され、対象ツールキットの UI スレッドで実行されます。Swing では Event Dispatch Thread、JavaFX では JavaFX Application Thread です。
4. コンポーネント UID には発行元のツールキットのプレフィックス（Swing は comp-、JavaFX は fx-）が付きます。これにより、混在するアプリケーションでも曖昧さがなくなります。
5. すべてのツールには MCP アノテーション（title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint）が付いているため、これらを尊重するクライアントは読み取り専用の 12 個のツールをそのまま実行でき、stop_app、close_window、evaluate_java の実行前には警告を表示できます。

すべてのツールのドキュメント（カテゴリ別ページ）については、docs/tools をご覧ください。1 ページのクイックリファレンスについては、docs/tool-reference.md をご覧ください。

スキル

skills ディレクトリには、AI コーディングエージェントに Swing MCP の効果的な使い方を教えるエージェントスキル（SKILL.md ファイル）が含まれています。内容は、基本的なワークフロー、UI テストのパターン、トラブルシューティングです。

ビルド

JDK 21 以降と Maven が必要です。

mvn verify

ヘッドレス環境では GUI 統合テストはスキップされます。CI では xvfb の下で実行されます。JavaFX 統合テストは failsafe を使って verify フェーズで実行されるため、mvn test だけでは実行されません。

実行

すべてをビルドするか、リリース済みの swing-mcp.mcpb を解凍します（2 つの JAR はその server/ フォルダーにあります）。その後、MCP クライアントにサーバーを登録します（クライアントごとの手順については docs/installation.md をご覧ください。対象は Claude Desktop、Claude Code、VS Code、Cursor、Devin Desktop、IntelliJ IDEA、Codex CLI、Gemini CLI です）。

{
  "mcpServers": {
    "swing": {
      "command": "java",
      "args": ["-jar", "/path/to/swing-mcp-server.jar"],
      "env": {
        "SWING_MCP_AGENT_JAR": "/path/to/swing-mcp-agent.jar"
      }
    }
  }
}

デモアプリで試してみましょう。

1. java -jar swing-mcp-demo/target/swing-mcp-demo-1.3.0.jar を指定して launch_app を実行します（または JavaFX デモの場合は swing-mcp-demo-fx/target/swing-mcp-demo-fx-1.3.0.jar を指定します）
2. take_snapshot を実行してコンポーネント UID を確認します
3. click、fill、select_option などを使って操作します

MCP Registry

このサーバーは MCP Registry に io.github.crosstech-solutions-bv/swing-mcp として公開されており、GitHub リリースに添付された MCPB バンドルとして配布されています。公開の仕組みについては docs/registry-publishing.md をご覧ください。

セキュリティに関する注意

• エージェントがリッスンするのはループバックインターフェースのみです。
• evaluate_java（対象 JVM 内での任意コード実行）はデフォルトで無効です。有効にするには swing.mcp.evaluate.enabled=true を設定してください。

セキュリティモデルの全容と脆弱性の報告方法については、SECURITY.md をご覧ください。

コントリビューション

コントリビューションを歓迎します。PR のワークフローについては CONTRIBUTING.md をご覧ください。リリース履歴は CHANGELOG.md にあります。

概要

Swing MCP は、AI を中心としたソフトウェアスタジオである CrossTech が開発・保守しています。企業が既存のソフトウェア（Web、クラウド、レガシーデスクトップ）を AI アシスタントに接続できる MCP コネクターを開発しています。crosstech.solutions/mcp

ライセンス

MIT