top

README

Filesystem MCP Server

This is a Go implementation of the Model Context Protocol (MCP) server for filesystem operations, based on Anthropic's reference implementation from modelcontextprotocol/servers.

Significant differences from the reference implementation include:

• The get_file_info and directory_tree commands return JSON data.
• The search_files tool supports gitignore-style exclude patterns.

Installation

Install the server with the following command:

go install github.com/optistar/mcp-server-filesystem/cmd/mcp-server-filesystem@latest

The executable will be installed in the Go bin directory, which is typically ~/go/bin. If this directory is not in your PATH, you may need to add it.

You can also set the GOBIN environment variable to change the installation directory.

Testing

A full test suite is included to ensure the server behaves as expected.

• The tests can be run normally with go test.
• A tester command packages the test suite as an MCP client that can be used to test the MCP server command, or another MCP server implementation.

Tools

The server provides the following tools for interacting with the filesystem:

• create_directory: Create a new directory or ensure a directory exists.
• directory_tree: Get a recursive tree view of files and directories as a JSON structure.
• edit_file: Make line-based edits to a text file.
• get_file_info: Retrieve detailed metadata about a file or directory.
• list_allowed_directories: Returns the list of directories that this server is allowed to access.
• list_directory: Get a detailed listing of all files and directories in a specified path.
• move_file: Move or rename files and directories.
• read_file: Read the complete contents of a file from the file system.
• read_multiple_files: Read the contents of multiple files simultaneously.
• search_files: Recursively search for files and directories matching a pattern.
• write_file: Create a new file or completely overwrite an existing file with new content.

Use the inspector for full details on each tool.

Other implementations

This repository is unrelated to mark3labs/mcp-filesystem-server.

License

The code in this repository is distributed under the MIT License.

Documentation

Index

• Variables
• func CreateDirectoryHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)
• func DefineCreateDirectoryTool() mcp.Tool
• func DefineDirectoryTreeTool() mcp.Tool
• func DefineEditFileTool() mcp.Tool
• func DefineGetFileInfoTool() mcp.Tool
• func DefineListAllowedDirectoriesTool() mcp.Tool
• func DefineListDirectoryTool() mcp.Tool
• func DefineMoveFileTool() mcp.Tool
• func DefineReadFileTool() mcp.Tool
• func DefineReadMultipleFilesTool() mcp.Tool
• func DefineSearchFilesTool() mcp.Tool
• func DefineWriteFileTool() mcp.Tool
• func DirectoryTreeHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)
• func EditFileHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)
• func ExpandHome(path string) string
• func GetFileInfoHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)
• func ListAllowedDirectoriesHandler(_ context.Context, _ mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)
• func ListDirectoryHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)
• func MoveFileHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)
• func ReadFileHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)
• func ReadMultipleFilesHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)
• func SearchFilesHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)
• func WriteFileHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)
• type Edit
• type ExcludeMatcher
  • func NewExcludeMatcher() ExcludeMatcher
• type FileInfo

Variables

var Tools = []tester.ToolHandler{
	{DefineReadFileTool(), ReadFileHandler},
	{DefineReadMultipleFilesTool(), ReadMultipleFilesHandler},
	{DefineWriteFileTool(), WriteFileHandler},
	{DefineEditFileTool(), EditFileHandler},
	{DefineCreateDirectoryTool(), CreateDirectoryHandler},
	{DefineListDirectoryTool(), ListDirectoryHandler},
	{DefineDirectoryTreeTool(), DirectoryTreeHandler},
	{DefineMoveFileTool(), MoveFileHandler},
	{DefineSearchFilesTool(), SearchFilesHandler},
	{DefineGetFileInfoTool(), GetFileInfoHandler},
	{DefineListAllowedDirectoriesTool(), ListAllowedDirectoriesHandler},
}

Define tools

Functions

func CreateDirectoryHandler

func CreateDirectoryHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)

func DefineCreateDirectoryTool

func DefineCreateDirectoryTool() mcp.Tool

func DefineDirectoryTreeTool

func DefineDirectoryTreeTool() mcp.Tool

func DefineEditFileTool

func DefineEditFileTool() mcp.Tool

func DefineGetFileInfoTool

func DefineGetFileInfoTool() mcp.Tool

func DefineListAllowedDirectoriesTool

func DefineListAllowedDirectoriesTool() mcp.Tool

func DefineListDirectoryTool

func DefineListDirectoryTool() mcp.Tool

func DefineMoveFileTool

func DefineMoveFileTool() mcp.Tool

func DefineReadFileTool

func DefineReadFileTool() mcp.Tool

Tool definitions

func DefineReadMultipleFilesTool

func DefineReadMultipleFilesTool() mcp.Tool

func DefineSearchFilesTool

func DefineSearchFilesTool() mcp.Tool

func DefineWriteFileTool

func DefineWriteFileTool() mcp.Tool

func DirectoryTreeHandler

func DirectoryTreeHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)

func EditFileHandler

func EditFileHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)

func ExpandHome

func ExpandHome(path string) string

Utility functions

func GetFileInfoHandler

func GetFileInfoHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)

func ListAllowedDirectoriesHandler

func ListAllowedDirectoriesHandler(_ context.Context, _ mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)

func ListDirectoryHandler

func ListDirectoryHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)

func MoveFileHandler

func MoveFileHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)

func ReadFileHandler

func ReadFileHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)

Tool handlers

func ReadMultipleFilesHandler

func ReadMultipleFilesHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)

func SearchFilesHandler

func SearchFilesHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)

func WriteFileHandler

func WriteFileHandler(_ context.Context, req mcp.CallToolRequest, allowedDirs []string) (*mcp.CallToolResult, error)

Types

type Edit

type Edit struct {
	OldText string `json:"oldText"`
	NewText string `json:"newText"`
}

Edit represents a single text replacement operation

type ExcludeMatcher

type ExcludeMatcher interface {
	AddPattern(pattern string) error
	Match(dirPath string, filePath string, info os.FileInfo) bool
}

func NewExcludeMatcher

func NewExcludeMatcher() ExcludeMatcher

NewExcludeMatcher creates a function that checks if a file should be excluded based on .gitignore patterns

type FileInfo

type FileInfo struct {
	Permissions string `json:"permissions"`
	Symlink     string `json:"symlink,omitempty"`
	Size        int64  `json:"size"`
	Created     string `json:"created,omitempty"`
	Modified    string `json:"modified"`
	Changed     string `json:"changed,omitempty"`
	Accessed    string `json:"accessed"`
}