Mcp Filesystem

セキュアなMCPファイルシステムサーバー

事前に定義されたディレクトリ内でファイルシステムへのアクセスを提供する、セキュアなModel Context Protocol（MCP）サーバー

概要   |    テクノロジー   |    ツール   |    インストール   |    使用方法   |    ライセンス

:bookmark: 概要

MCP Filesystem Serverは、Model Context Protocolを通じてAIモデルにセキュアなファイルシステムアクセスを提供します。 厳格なパス検証を適用し、事前に定義されたディレクトリへのアクセスのみを許可します。

:computer: テクノロジー

• TypeScript
• Node.js
• MCP SDK
• Zod
• Docker
• pnpm

:wrench: ツール

• Visual Studio Code
• ESLint
• Prettier
• Vitest
• Docker Compose

:package: インストール

:heavy_check_mark: 前提条件

以下のソフトウェアをインストールする必要があります。

• Node.js (>=18.0.0)
• Git
• pnpm (>=8.0.0)
• Docker（任意）
• Docker Compose（任意）

:arrow_down: リポジトリのクローン

  $ git clone https://github.com/gabrielmaialva33/mcp-filesystem.git
  $ cd mcp-filesystem

:arrow_forward: アプリケーションの実行

ローカル開発

  # Install dependencies
  $ pnpm install

  # Build the application
  $ pnpm build

  # Run the server (specify directory to allow access to)
  $ pnpm start /path/to/allowed/directory

  # Or use configuration file
  $ pnpm start --config=config.json

NPMパッケージを使用する場合

  # Install globally
  $ npm install -g @gabrielmaialva33/mcp-filesystem

  # Run the server
  $ mcp-filesystem /path/to/allowed/directory

  # Or use with npx (no installation needed)
  $ npx @gabrielmaialva33/mcp-filesystem /path/to/allowed/directory

  # Create a sample configuration file
  $ npx @gabrielmaialva33/mcp-filesystem --create-config=config.json

Dockerを使用する場合

  # Build the Docker image
  $ docker build -t gabrielmaialva33/mcp-filesystem .

  # Run using Docker
  $ docker run -i --rm -v /path/to/data:/data:ro gabrielmaialva33/mcp-filesystem /data

  # Use with config file
  $ docker run -i --rm -v /path/to/config.json:/app/config.json -v /path/to/data:/data gabrielmaialva33/mcp-filesystem --config=/app/config.json

Docker Composeを使用する場合

  # Create a data directory
  $ mkdir -p data

  # Start the server
  $ docker-compose up -d

:gear: 使用方法

Claude Desktopでの使用

Claude Desktopは、ファイルシステムへのアクセスにこのMCPサーバーを使用するよう設定できます。次の内容を claude_desktop_config.jsonに追加してください。

ローカルインストールを使用する場合（推奨）

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem",
      "args": [
        "/Users/gabrielmaia/Documents",
        "/Users/gabrielmaia/Desktop",
        "/Users/gabrielmaia/Downloads"
      ]
    }
  }
}

実行ファイルをグローバルに利用できるようにしてください。

# Make the binary executable
chmod +x /Users/gabrielmaia/.nvm/versions/node/v22.14.0/bin/mcp-filesystem

NPXを使用する場合

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@gabrielmaialva33/mcp-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Dockerを使用する場合

注：Dockerを使用する場合、すべてのディレクトリをデフォルトで/projectsにマウントする必要があります。roフラグを追加すると、ディレクトリは読み取り専用になります。

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount",
        "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount",
        "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "gabrielmaialva33/mcp-filesystem",
        "/projects"
      ]
    }
  }
}

利用可能なツール

MCP Filesystem Serverでは、次のツールを利用できます。

ファイルシステム操作

• read_file: ファイルの内容を読み取ります
• read_multiple_files: 複数のファイルを一度に読み取ります
• write_file: ファイルを作成または上書きします
• edit_file: 差分をプレビューしながら正確に編集します
• create_directory: ディレクトリを再帰的に作成します
• list_directory: ディレクトリの内容を一覧表示します
• directory_tree: 再帰的なツリー表示を取得します
• move_file: ファイルを移動または名前変更します
• search_files: パターンに一致するファイルを検索します
• get_file_info: ファイルのメタデータを取得します
• list_allowed_directories: アクセス可能なディレクトリを確認します

システムおよびネットワーク操作

• get_metrics: サーバーのパフォーマンスメトリクスを表示します（v0.3.0+）
• execute_command: システムコマンドを安全に実行します（v0.3.1+）
• curl_request: 外部 API への HTTP リクエストを実行します（v1.2.0 で提供予定）

curl_request ツールの使用（v1.2.0 で提供予定）

curl_request ツールを使うと、外部 API への HTTP リクエストを実行できます。

// Example: Making a GET request with authentication
curl_request({
  url: 'https://api.example.com/data',
  method: 'GET',
  headers: {
    Authorization: 'Bearer your_token_here',
  },
})

// Example: POST request with JSON data
curl_request({
  url: 'https://api.example.com/create',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  data: '{"name":"Example","value":123}',
})

詳細な例については、docs/curl-tool-examples.md ファイルをご覧ください。

:sparkles: 機能

コア機能

• 安全なアクセス: 厳格なパス検証により、不正なアクセスを防止します
• ファイル操作: ファイルの読み取り、書き込み、編集、移動ができます
• ディレクトリ操作: ディレクトリの作成、一覧表示、ツリー表示の取得、検索ができます
• メタデータへのアクセス: ファイルおよびディレクトリの情報を表示します
• コマンド実行: 厳格な検証のもと、システムコマンドを安全に実行します
• Docker サポート: Docker と Docker Compose による簡単なデプロイが可能です

v0.3.0 の新機能

• 構造化ログ: 複数のレベル（debug、info、warn、error）による詳細なログ記録
• パフォーマンスメトリクス: 操作数、エラー、実行時間を追跡します
• 設定管理: JSON 設定ファイルをサポートします
• パスキャッシュ: 頻繁にアクセスするパスのパフォーマンスを向上させます
• エラーハンドリングの改善: 構造化された情報を含む専用のエラー型
• ファイルサイズの検証: 過度に大きなファイルの読み込みを防ぎます
• CLI の改善: ヘルプコマンド、バージョン情報、設定生成

設定オプション

次のコマンドを使って設定ファイルを作成できます。

$ mcp-filesystem --create-config=config.json

設定例：

{
  "allowedDirectories": ["/path/to/allowed/dir1", "/path/to/allowed/dir2"],
  "logLevel": "info",
  "logFile": "/path/to/logs/mcp-filesystem.log",
  "serverName": "secure-filesystem-server",
  "serverVersion": "0.3.0",
  "cache": {
    "enabled": true,
    "maxSize": 1000,
    "ttlMs": 60000
  },
  "metrics": {
    "enabled": true,
    "reportIntervalMs": 60000
  },
  "security": {
    "maxFileSize": 10485760,
    "allowSymlinks": true,
    "validateRealPath": true
  }
}

:writing_hand: 作者

Gabriel Maia

ライセンス

MIT ライセンス

© 2024-present Maia