Skip to main content
Glama
enesjakozh
cyanheads

Filesystem MCP Server

by cyanheads
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

ファイルシステムMCPサーバー

タイプスクリプト モデルコンテキストプロトコルバージョンライセンス状態 GitHub

強力でプラットフォームに依存しないファイル システム機能を使用して AI エージェントを強化します。

このモデルコンテキストプロトコル（MCP）サーバーは、AIエージェントがローカルファイルシステムとやり取りするための安全で信頼性の高いインターフェースを提供します。包括的なログ記録、エラー処理、セキュリティ対策を備えた本番環境対応のTypeScript基盤を備え、ファイルとディレクトリの読み取り、書き込み、更新、管理を可能にします。

目次

Related MCP server: MCP Filesystem Server

概要

モデルコンテキストプロトコル（MCP）は、AIモデルが外部ツールやデータソース（リソース）と安全にやり取りできるようにする標準フレームワークです。このサーバーはMCP標準を実装し、重要なファイルシステム操作をツールとして公開することで、AIエージェントが以下のことを実現できるようにします。

  • ファイルの内容を読み取り、分析します。

  • ファイルを作成、変更、または上書きします。

  • ディレクトリとファイル パスを管理します。

  • ファイル内で対象を絞った更新を実行します。

TypeScript で構築されたこのサーバーは、型の安全性、モジュール性、堅牢なエラー処理を重視しており、AI ワークフローへの信頼性の高い統合に適しています。

建築

サーバーは、明瞭性と保守性のために階層化アーキテクチャを採用しています。

flowchart TB
    subgraph API["API Layer"]
        direction LR
        MCP["MCP Protocol Interface"]
        Val["Input Validation (Zod)"]
        San["Path Sanitization"]

        MCP --> Val --> San
    end

    subgraph Core["Core Services"]
        direction LR
        Config["Configuration"]
        Logger["Logging (Winston)"]
        Error["Error Handling"]
        Server["MCP Server Logic"]
        State["Session State"]

        Config --> Server
        Logger --> Server & Error
        Error --> Server
        State --> Server
    end

    subgraph Implementation["Tool Implementation"]
        direction LR
        ToolLogic["Filesystem Tools"]
        Utils["Core Utilities"]

        ToolLogic --> Server
        Utils -- Used by --> ToolLogic
        Utils -- Used by --> Core
    end

    San --> ToolLogic

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    class API,Core,Implementation layer
    class MCP,Val,San,Config,Logger,Error,Server,State,ToolLogic,Utils component

  • API レイヤー: MCP 通信を処理し、Zod を使用して入力を検証し、パスをサニタイズします。

  • コア サービス: 構成、ログ記録、エラー レポート、セッション状態 (既定の作業ディレクトリなど)、およびメインの MCP サーバー インスタンスを管理します。

  • ツール実装: 共有ユーティリティを活用して、各ファイルシステム ツールの特定のロジックが含まれています。

特徴

  • 包括的なファイル操作: ファイルとディレクトリの読み取り、書き込み、一覧表示、削除、移動、コピーを行うツール。

  • ターゲット更新: update_fileツールを使用すると、プレーン テキストと正規表現をサポートし、ファイル内で正確な検索と置換操作を実行できます。

  • セッション対応パス管理: set_filesystem_defaultツールは、セッション中に相対パスを解決するためのデフォルトの作業ディレクトリを確立します。

  • セキュリティ第一：組み込みのパスサニタイズ機能により、ディレクトリトラバーサル攻撃を防止します。オプションのベースディレクトリ制限により、セキュリティが強化されます。

  • 堅牢な基盤: 以下の製品レベルのユーティリティが含まれています:

    • 構造化されたコンテキスト認識型のログ記録。

    • 特定のエラー コードを使用した標準化されたエラー処理。

    • リクエストトレース用の一意の ID 生成。

    • 入力のサニタイズ。

    • オプションのレート制限 (util ファイルは作成されましたが、まだ統合されていません)。

  • 型安全性: 信頼性と保守性を向上させるために TypeScript で完全に実装されています。

インストール

手順

  1. リポジトリをクローンします。

    git clone https://github.com/cyanheads/filesystem-mcp-server.git
cd filesystem-mcp-server

  2. 依存関係をインストールします:

    npm install

  3. プロジェクトをビルドします。

    npm run build

    これにより、TypeScriptコードがdist/ディレクトリ内のJavaScriptにコンパイルされ、メインスクリプトが実行可能ファイルになります。実行ファイルはdist/index.jsに保存されます。

構成

環境変数を使用してサーバーを構成します。

  • FS_BASE_DIRECTORY (オプション、セキュリティのために推奨):

    • 絶対パスに設定すると、サーバーによるすべてのファイル操作は、このディレクトリとそのサブディレクトリ内に厳密に制限されます。これにより、AIエージェントが意図したスコープ外のファイルにアクセスするのを防ぎます。

    • 例: FS_BASE_DIRECTORY=/Users/casey/safe-agent-files

  • LOG_LEVEL (オプション):

    • ログの詳細度を制御します。オプション: error 、 warn 、 info 、 http 、 verbose 、 debug 、 silly 。

    • デフォルトはinfoです。

  • LOG_DIR (オプション):

    • ログ ファイル ( combined.log 、 error.log ) が保存されるディレクトリを指定します。

    • デフォルトは、サーバーの実行ディレクトリを基準とした./logsです。

MCPクライアントでの使用

MCP クライアント (AI アシスタントなど) がこのサーバーを使用できるようにするには:

  1. **サーバーの実行:**ターミナルからサーバーを起動します。

    node dist/index.js
# Or if you are in the project root:
# npm start

  2. クライアントの設定： MCPクライアントの設定にサーバーを追加します。具体的な方法はクライアントによって異なりますが、通常は以下の項目を指定します。

    • コマンド: node

    • **引数:**構築されたサーバー実行可能ファイルへの絶対パス (例: /path/to/filesystem-mcp-server/dist/index.js )。

    • **環境変数 (オプション):**必要に応じてFS_BASE_DIRECTORY 、 LOG_LEVEL 、またはLOG_DIRを設定します。

    MCP 設定の例 (概念):

    {
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp-server/dist/index.js"],
      "env": {
        "FS_BASE_DIRECTORY": "/path/to/base/directory",
        "LOG_LEVEL": "debug"
      },
      "disabled": false,
      "autoApprove": []
    }
    // ... other servers
  }
}

設定して実行すると、クライアントはサーバーと利用可能なツールを検出します。

利用可能なツール

サーバーは、ファイルシステムの対話用に次のツールを公開します。

道具

説明

set_filesystem_default

現在のセッションのデフォルトの絶対パスを設定します。以降のツール呼び出しで使用される相対パスは、このデフォルトに基づいて解決されます。サーバーの再起動時にリセットされます。

read_file

指定されたファイルの内容全体をUTF-8テキストとして読み取ります。相対パス（デフォルトに対して解決）または絶対パスを受け入れます。

write_file

指定されたファイルにコンテンツを書き込みます。ファイル（および必要な親ディレクトリ）が存在しない場合は作成し、存在する場合は上書きします。相対パスまたは絶対パスを指定できます。

update_file

{search, replace}ブロックの配列を使用して、既存のファイル内で対象を絞った検索と置換を実行します。ローカライズされた変更に最適です。プレーンテキストまたは正規表現による検索（ useRegex: true ）と、すべての出現箇所の置換（ replaceAll: true ）をサポートします。相対パスまたは絶対パスを指定できます。ファイルは存在している必要があります。

list_files

指定されたパス内のファイルとディレクトリを一覧表示します。再帰的な一覧表示（ includeNested: true ）とエントリ数の制限（ maxEntries ）のオプションがあります。フォーマットされたツリー構造を返します。相対パスまたは絶対パスを指定できます。

delete_file

特定のファイルを完全に削除します。相対パスまたは絶対パスを指定できます。

delete_directory

ディレクトリを完全に削除します。空でないディレクトリとその内容を削除するには、 recursive: true使用してください（注意して使用してください）。相対パスまたは絶対パスを指定できます。

create_directory

指定されたパスに新しいディレクトリを作成します。デフォルト（ create_parents: true ）では、必要な親ディレクトリも作成されます。相対パスまたは絶対パスを指定できます。

move_path

ファイルまたはディレクトリをソースパスからターゲットパスに移動または名前変更します。相対パスと絶対パスのどちらでも指定できます。

copy_path

ファイルまたはディレクトリをコピー元パスからコピー先パスにコピーします。ディレクトリの場合、デフォルトで再帰的にコピーします（ recursive: true ）。相対パスまたは絶対パスを指定できます。

詳細な入力/出力スキーマ (Zod/JSON スキーマ) については、ツール登録ファイル (

プロジェクト構造

コードベースは、明瞭性と保守性を考慮して構成されています。

filesystem-mcp-server/
├── dist/                 # Compiled JavaScript output (after npm run build)
├── logs/                 # Log files (created at runtime)
├── node_modules/         # Project dependencies
├── src/                  # TypeScript source code
│   ├── config/           # Configuration loading (index.ts)
│   ├── mcp-server/       # Core MCP server logic
│   │   ├── server.ts     # Server initialization and tool registration
│   │   ├── state.ts      # Session state management (e.g., default path)
│   │   └── tools/        # Individual tool implementations (one subdir per tool)
│   │       ├── readFile/
│   │       │   ├── index.ts
│   │       │   ├── readFileLogic.ts
│   │       │   └── registration.ts
│   │       └── ...       # Other tools (writeFile, updateFile, etc.)
│   ├── types-global/     # Shared TypeScript types and interfaces
│   │   ├── errors.ts     # Custom error classes and codes
│   │   ├── mcp.ts        # MCP related types
│   │   └── tool.ts       # Tool definition types
│   ├── utils/            # Reusable utility modules
│   │   ├── errorHandler.ts
│   │   ├── idGenerator.ts
│   │   ├── index.ts
│   │   ├── logger.ts
│   │   ├── rateLimiter.ts
│   │   ├── requestContext.ts
│   │   └── sanitization.ts
│   └── index.ts          # Main application entry point
├── .clinerules           # Cheatsheet for LLM assistants
├── .gitignore
├── LICENSE
├── package.json
├── package-lock.json
├── README.md             # This file
└── tsconfig.json         # TypeScript compiler options

現在の構造の詳細なライブビューを表示するには、 npm run treeを実行します。

**開発者向けメモ：**このリポジトリには.clinerulesファイルが含まれています。このチートシートは、LLMコーディングアシスタントに、コードベースのパターン、ファイルの場所、使用例など、重要なコンテキストを提供します。サーバーの進化に合わせて更新してください。

ライセンス

このプロジェクトはApache License 2.0に基づいてライセンスされています。詳細はLICENSEファイルをご覧ください。

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

View all tools

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/cyanheads/filesystem-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server