MCP Filesystem

🚀 MCP Filesystem Protocol Server

A Model Context Protocol (MCP) server that provides file resources for each working directory and sends change notifications.

🚀 Quick Start

A Model Context Protocol (MCP) server that offers file resources for every working directory and dispatches change notifications.

⚠️ Status

⚠️ Pre-Beta Quality ⚠️

"It works on my machine." Feel free to submit issues ❤️

✨ Features

• Resources: Create an MCP resource for each file in the workspace.
• .gitignore Support: Respect .gitignore rules.
• Change Notifications: Detect file changes, additions, and deletions.
• MIME Type Recognition and Encoding Handling: Identify file types and handle multiple text encodings.

📦 Installation

Install Go: Follow the instructions at https://golang.org/doc/install.

Get or update this server:

go install github.com/isaacphi/mcp-filesystem@latest

Add the following to your client configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem",
      "args": ["--workspace", "/path/to/your/repository"]
    }
  }
}

Replace /path/to/your/repository with the absolute path of your project.

💻 Usage Examples

Basic Usage

Your client can access and reference all non-ignored files in the workspace as MCP resources. Each file is registered as an independent resource with appropriate MIME type detection.

Client Requirements

Your client needs to support the following MCP features:

• Resource Listing: The ability to list and access all resources exposed by the server.
• Change Notifications: Support for receiving notifications/resources/list_changed events.
• Resource Content Access: The ability to request and render resource content and its appropriate MIME type.

📚 Documentation

This project uses the following technologies:

• mark3labs/mcp-go for MCP communication.
• fsnotify to monitor file system events.
• go-gitignore to parse .gitignore files.

🔧 Technical Details

Development

Clone the repository:

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

Install dependencies:

go mod download

Build the project:

go build

Configure the client to use the locally built version:

{
  "mcpServers": {
    "filesystem": {
      "command": "/full/path/to/your/mcp-filesystem/mcp-filesystem",
      "args": ["--workspace", "/path/to/repository"],
      "env": {
        "DEBUG": "1"
      }
    }
  }
}

Feedback

Please submit detailed issues with all relevant information.

Set the DEBUG environment variable to enable detailed logging:

"env": {
  "DEBUG": "1"
}

Planned Features

• [x] Resources for each file in the workspace
• [x] .gitignore support
• [x] Change notifications
• [ ] Standardize the MCP protocol to support more clients (Claude Desktop)
• [ ] Configurable support for line numbers
• [ ] Subscription to resource updates
• [ ] Additional ignore patterns (beyond .gitignore)
• [ ] Delayed notifications to handle high-frequency file changes
• [ ] info, create, edit, and delete tools