Ubuntu MCP Server

🚀 セキュアなUbuntu MCPサーバー

🔒 セキュリティを最優先 するモデルコンテキストプロトコル（MCP）サーバーで、Ubuntuシステムの安全な操作を実現します。

堅牢で本番環境に対応したモデルコンテキストプロトコル（MCP）サーバーで、AIアシスタントにUbuntuシステム操作への安全で制御されたアクセスを提供します。包括的なセキュリティ制御、監査ログ、そして深度防御の原則に基づいて構築されています。

✨ 主な機能

🛡️ セキュリティを最優先したアーキテクチャ

• パストラバーサル保護 - 許可リスト/拒否リストによるシンボリックリンク解決
• コマンドサニタイズ - 安全な引数解析によるシェルインジェクション防止
• リソース制限 - ファイルサイズ、実行タイムアウト、出力サイズの制御
• 包括的な監査ログ - すべての操作をユーザー属性とともに記録
• 深度防御 - フェイルセーフデフォルトを持つ複数のセキュリティ層

🎯 核心機能

• ファイル操作 - パーミッション検証を伴うディレクトリの読み取り、書き込み、一覧表示
• コマンド実行 - ホワイトリスト/ブラックリストによる安全なシェルコマンド実行
• システム情報 - OSの詳細、メモリ、ディスク使用量の監視
• パッケージ管理 - APTパッケージの検索と一覧表示（インストールには明示的な設定が必要）

🏗️ 本番環境対応

• 関心事の明確な分離によるモジュール設計
• 意味のあるエラーメッセージを伴う包括的なエラーハンドリング
• セキュリティ検証テストを含む広範なテストスイート
• さまざまなユースケースと環境に対応した設定可能なポリシー
• ゼロ依存のセキュリティ - コアセキュリティは外部パッケージに依存しない

🚀 クイックスタート

前提条件

• Ubuntu 18.04以上（20.04、22.04、24.04でテスト済み）
• Python 3.9以上
• 標準のUnixユーティリティ（ls、cat、echoなど）

インストール

# リポジトリをクローンする
git clone https://github.com/yourusername/secure-ubuntu-mcp.git
cd secure-ubuntu-mcp

# 仮想環境を作成してアクティブ化する
python3 -m venv .venv
source .venv/bin/activate

# 依存関係をインストールする
pip install -r requirements.txt

# 組み込みテストでインストールを検証する
python main.py --test

基本的な使用法

# 安全なポリシーで起動する（推奨）
python main.py --policy secure

# 開発用ポリシーで起動する（制限が少ない）
python main.py --policy dev

# セキュリティ対策をテストする
python main.py --security-test

🔧 統合

Claude Desktop

LinuxでClaude Desktopを入手する

公式サポート: Claude Desktopは公式にLinuxをサポートしていませんが、コミュニティが解決策を作成しています！

推奨方法: @aaddrickによるコミュニティDebianパッケージを使用します。

# Linux用のClaude Desktopをダウンロードしてインストールする
wget https://github.com/aaddrick/claude-desktop-debian/releases/latest/download/claude-desktop_latest_amd64.deb
sudo dpkg -i claude-desktop_latest_amd64.deb
sudo apt-get install -f  # 依存関係の問題を修正する

他の方法やトラブルシューティングについては、https://github.com/aaddrick/claude-desktop-debian を参照してください。

設定

Claude Desktopをインストールしたら、設定ファイル（~/.config/claude-desktop/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "secure-ubuntu": {
      "command": "/path/to/secure-ubuntu-mcp/.venv/bin/python3",
      "args": ["/path/to/secure-ubuntu-mcp/main.py", "--policy", "secure"],
      "env": {
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

⚠️ 重要: 絶対パスと仮想環境のPythonインタープリターを使用してください。

検証: Claude Desktopを再起動した後、「secure-ubuntu」が接続されたサーバーとして表示され、Claudeがシステム制御ツールにアクセスできるようになります。

その他のMCPクライアント

このサーバーは標準のMCPプロトコルを実装しており、MCP互換のクライアントと互換性があります。

# mcp Pythonクライアントの例
import asyncio
from mcp.client import ClientSession

async def example():
    # サーバーに接続する
    # 実装はあなたのMCPクライアントに依存します
    pass

🛡️ セキュリティポリシー

安全なポリシー（デフォルト）

本番環境や信頼できない環境で推奨されます。

• 許可されたパス: ~/, /tmp, /var/tmp
• 禁止されたパス: /etc, /root, /boot, /sys, /proc, /dev, /usr, /bin, /sbin
• コマンドホワイトリスト: ls, cat, echo, pwd, whoami, date, find, grep, apt（検索のみ）
• リソース制限: 1MBのファイル、15秒のタイムアウト、256KBの出力
• sudo: 無効
• シェル実行: 無効（安全な直接実行を使用）

開発用ポリシー

開発環境では制限が少なくなっています。

• 追加で許可されたパス: /opt, /usr/local
• 制限の緩和: より多くのシステム領域へのアクセス
• より大きな制限: 10MBのファイル、60秒のタイムアウト、1MBの出力
• より多くのコマンド: ほとんどの開発ツールが許可される
• sudo: デフォルトでは無効（有効にすることもできます）

カスタムポリシー

独自のセキュリティポリシーを作成します。

from main import SecurityPolicy

custom_policy = SecurityPolicy(
    allowed_paths=["/your/custom/paths"],
    forbidden_paths=["/sensitive/areas"],
    allowed_commands=["safe", "commands"],
    forbidden_commands=["dangerous", "commands"],
    max_command_timeout=30,
    allow_sudo=False,  # 極めて注意して使用する
    audit_actions=True
)

🔍 利用可能なツール

ファイル操作

• list_directory(path) - メタデータ付きでディレクトリの内容を一覧表示する
• read_file(file_path) - サイズ検証を伴うファイル内容の読み取り
• write_file(file_path, content, create_dirs=False) - アトミック操作による書き込み

システム操作

• execute_command(command, working_dir=None) - 安全にシェルコマンドを実行する
• get_system_info() - OS、メモリ、ディスク情報を取得する

パッケージ管理

• search_packages(query) - APTリポジトリを検索する
• install_package(package_name) - パッケージの可用性を確認する（一覧表示のみ）

🔒 セキュリティ機能

一般的な攻撃からの保護

パストラバーサル防止:

# これらはすべてブロックされます:
../../../etc/passwd
/etc/passwd
/tmp/../etc/passwd
symlinks_to_sensitive_files

コマンドインジェクション防止:

# これらはすべてブロックされます:
echo hello; rm -rf /
echo `cat /etc/passwd`
echo $(whoami)
ls | rm -rf /

リソース枯渇保護:

• ファイルサイズ制限によりメモリ枯渇を防止
• 実行タイムアウトによりハングしたプロセスを防止
• 出力サイズ制限によりログの洪水を防止
• ディレクトリ一覧表示制限により列挙攻撃を防止

監査トレイル

すべての操作は以下の情報とともに記録されます。

• ユーザー属性
• タイムスタンプと操作タイプ
• 完全なパス解決
• 成功/失敗ステータス
• セキュリティ違反の詳細

🧪 テスト

機能テスト

# 核心機能をテストする
python main.py --test

セキュリティ検証

# 包括的なセキュリティテストを実行する
python main.py --security-test

手動テスト

# MCPプロトコルを直接テストする
python test_client.py --simple

📊 使用例

AIアシスタントと統合した後の使用例です。

システム監視:

"システムの状態とディスク容量を確認してください"

ファイル管理:

"ホームディレクトリのファイルを一覧表示し、最も大きいファイルを表示してください"

開発タスク:

"Pythonがインストールされているか確認し、バージョンを表示してください"

ログ分析:

"プロジェクトディレクトリ内のエラーファイルを探してください"

⚙️ 設定

環境変数

• MCP_LOG_LEVEL - ログレベル（DEBUG、INFO、WARNING、ERROR）
• MCP_POLICY - セキュリティポリシー（secure、dev）
• MCP_CONFIG_PATH - カスタム設定ファイルのパス

設定ファイル

カスタム設定用にconfig.jsonを作成します。

{
  "server": {
    "name": "secure-ubuntu-controller",
    "version": "1.0.0",
    "log_level": "INFO"
  },
  "security": {
    "policy_name": "secure",
    "allowed_paths": ["~/", "/tmp"],
    "max_command_timeout": 30,
    "allow_sudo": false,
    "audit_actions": true
  }
}

🛠️ 開発

新しいツールの追加

@mcp.tool("your_tool_name")
async def your_tool(param: str) -> str:
    """AIアシスタント用のツール説明"""
    try:
        # 安全な操作のためにコントローラーメソッドを使用する
        result = controller.safe_operation(param)
        return json.dumps(result, indent=2)
    except Exception as e:
        return json.dumps({"error": str(e)}, indent=2)

セキュリティの拡張

def create_custom_policy() -> SecurityPolicy:
    """カスタムセキュリティポリシーを作成する"""
    return SecurityPolicy(
        allowed_paths=["/your/paths"],
        forbidden_commands=["dangerous", "commands"],
        # ... 他の設定
    )

🔧 トラブルシューティング

一般的な問題

"サーバーがハングしているように見える"

• これは正常な動作です！MCPサーバーは継続的に実行され、stdioを介して通信します。
• サーバーはMCPプロトコルメッセージを待機しています。

"ModuleNotFoundError: No module named 'mcp'"

• 仮想環境のPythonインタープリターを使用していることを確認してください。
• Claude Desktopの設定で.venv/bin/python3の完全パスを使用していることを確認してください。

"SecurityViolation"エラー

• セキュリティポリシーでパス/コマンドが許可されているか確認してください。
• /tmp/ubuntu_mcp_audit.logの監査ログを確認してください。
• テスト用に開発用ポリシーを使用することを検討してください。

"Permission denied"エラー

• ユーザーが要求されたパスにアクセスできることを確認してください。
• ls -laでファイル/ディレクトリのパーミッションを確認してください。

デバッグモード

# 詳細なログを有効にする
python main.py --log-level DEBUG --policy secure

# 監査ログを確認する
tail -f /tmp/ubuntu_mcp_audit.log

🤝 コントリビューション

コントリビューションを歓迎します！詳細については、コントリビューションガイドラインを参照してください。

開発環境のセットアップ

1. リポジトリをフォークする
2. 機能ブランチを作成する: git checkout -b feature/amazing-feature
3. テストを含めて変更を加える
4. すべてのテストが通過することを確認する: python main.py --test && python main.py --security-test
5. プルリクエストを送信する

コード標準

• PEP 8のスタイルガイドラインに従う
• すべての公開関数に型ヒントを追加する
• 包括的なドキュメント文字列を含める
• 新しい機能に対してテストを書く
• セキュリティを最優先する原則を維持する

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

🔐 セキュリティ開示

セキュリティバグを発見した場合は、公開イシューを作成する代わりに、[radjackbartok@proton.me]にメールで連絡してください。私たちはセキュリティを真摯に受け止め、迅速に対応します。

🙏 謝辞

• モデルコンテキストプロトコルチームに、優れたプロトコルを提供してくれたことに感謝します。
• セキュリティ研究者や情報セキュリティコミュニティに、ベストプラクティスを提供してくれたことに感謝します。
• Pythonセキュリティコミュニティに、継続的なガイダンスを提供してくれたことに感謝します。

📈 ロードマップ

• [ ] 強化されたロギング - より多くのコンテキストを持つ構造化JSONロギング
• [ ] コンテナサポート - Docker統合とコンテナ対応ポリシー
• [ ] ネットワークツール - 安全なネットワーキングユーティリティ（ping、tracerouteなど）
• [ ] プロセス管理 - 安全なプロセス監視と制御
• [ ] 設定UI - ポリシー管理用のWebインターフェース
• [ ] 統合テスト - 包括的なエンドツーエンドテスト
• [ ] パフォーマンス最適化 - キャッシングとパフォーマンスの改善
• [ ] マルチユーザーサポート - ロールベースのアクセス制御

セキュリティを意識したAIコミュニティのために作られました

💡 アドバイス: 安全なポリシーから始め、必要に応じて段階的にパーミッションを増やしましょう。パーミッションを追加する方が、セキュリティインシデントから回復するよりも簡単です！