linux-mcp-server

Linux MCP Server

Spring Boot と Spring AI を基盤に構築された Model Context Protocol (MCP) サーバーです。ローカルおよびリモートの Linux ホストで、安全に Shell コマンドを実行できます。MCP 標準インターフェースを介して、Claude Desktop などの MCP 対応 AI アシスタントから直接接続でき、AI の運用管理能力を拡張します。

目次

• 概要
• 主な機能
• クイックスタート
• 設定
• AI アシスタントとの統合
• セキュリティに関する推奨事項
• 開発とデバッグ
• ライセンス

概要

Linux MCP Server は Shell の実行を MCP ツール executeShell としてラップし、Spring AI によって MCP Server に自動登録します。クライアントは標準の MCP 呼び出しを通じて、対象ホストとコマンドを指定するだけで、ローカルまたはリモートの Linux マシン上でスクリプトを実行し、標準出力とエラーログを取得できます。

主な機能

• デュアルモード実行：コマンドの実行場所を自動判定し、ローカルプロセスの実行とリモート SSH 実行に対応します。
• 接続プール管理：Caffeine キャッシュを使用して SSH 接続を再利用し、デフォルトでは 5 分後に自動的に期限切れとなり、削除されます。
• シンプルな設定：シンプルな hosts.json でリモートホストの一覧を管理でき、再起動すると設定が反映されます。
• Spring Boot とのネイティブ統合：すぐに使える mvn spring-boot:run と実行可能 JAR によるデプロイに対応し、デフォルトでポート 3001 をリッスンします。
• MCP プロトコル互換：spring-ai-starter-mcp-server-webmvc に依存し、STREAMABLE HTTP チャネルに対応するため、主要な MCP クライアントで利用できます。

クイックスタート

環境の準備

• Java 17+
• Maven 3.6+（リポジトリに同梱されている ./mvnw/mvnw.cmd の使用を推奨）
• SSH サービスが稼働している対象 Linux ホスト

コードの取得

git clone <repository-url>
cd linux-mcp-server

リモートホストの設定

src/main/resources/hosts.json を編集します：

[
  {
    "ip": "192.168.1.100",
    "username": "devops",
    "password": "your_password"
  }
]

• ip：対象ホストのアドレスです。executeShell の machineIp と一致させる必要があります。
• username/password：SSH ログイン認証情報です。現在はパスワード認証を使用していますが、コードを拡張すれば鍵認証にも対応できます。

⚠️ 本番環境の認証情報をバージョン管理に登録しないことをお勧めします。環境変数または設定センターを使用して機密情報を管理してください。

サービスの起動

開発環境では、次のコマンドを直接実行します：

mvn spring-boot:run

または、パッケージ化して単独で実行します：

mvn clean package
java -jar target/linux-mcp-server-1.0.0.jar

起動が完了すると、デフォルトで http://localhost:3001/mcp に MCP 接続エンドポイントが公開されます。

設定

主要な設定は src/main/resources/application.yml にまとめられています：

server:
  port: 3001            # MCP Server 监听端口
spring.ai.mcp.server:
  name: linux-mcp-server
  version: 1.0.0
  protocol: STREAMABLE  # 使用流式 HTTP 传输
  streamable-http:
    mcp-endpoint: /mcp  # MCP 入口路径

カスタマイズする場合：

• ポートまたは mcp-endpoint を変更する場合は、MCP クライアントの設定も忘れずに更新してください。
• 接続するホストを追加する場合は、hosts.json にエントリーを追加してサービスを再起動してください。

AI アシスタントとの統合

Claude Desktop を例に、claude_desktop_config.json に次の設定を追加します：

{
  "mcpServers": [
    {
      "name": "linux-mcp-server",
      "type": "http",
      "command": "http",
      "args": ["http://localhost:3001/mcp"]
    }
  ]
}

接続に成功すると、Claude はツール executeShell を自動的に検出します：

• machineIp（省略可）：空またはローカルアドレスの場合、ローカルマシンでコマンドを実行します。
• path（省略可）：コマンドの実行ディレクトリです。省略時は / になります。
• shell（必須）：実行する完全なコマンドです。

セキュリティに関する推奨事項

• 認証情報の管理：hosts.json にはパスワードが平文で保存されます。開発環境または管理された環境でのみ使用してください。本番環境では鍵認証または外部の安全なストレージに切り替えてください。
• ホストの検証：現在は PromiscuousVerifier を使用してホストフィンガープリントの検証をスキップしています。中間者攻撃を防ぐため、本番環境へのデプロイ前に既知のホスト一覧を使用する方式に置き換えてください。
• 最小権限：リモートマシンには権限を制限したユーザーを作成し、root アカウントの使用を避け、実行可能なコマンドの範囲を制限してください。
• ネットワーク制限：ファイアウォール／セキュリティグループを使用して、MCP Server と対象ホストへのアクセス元を制限してください。

開発とデバッグ

• 主なコードは src/main/java/com/doodl6/mcp/linux にあります。必要に応じて新しいツールメソッドを追加できます。
• SSH キャッシュのポリシーを調整する場合は、RemoteShellService の CACHE_DURATION_MINUTES、MAX_CACHE_SIZE を変更してください。
• 変更後は、executeShell を手動で一度（ローカルとリモートで各一度）実行し、出力とエラー処理のロジックを確認することをお勧めします。

ライセンス

このプロジェクトは MIT ライセンス に基づくオープンソースであり、自由に使用および二次開発できます。