# mark3labs/mcp-filesystem-server architecture

> Architecture diagram of the GitHub repository mark3labs/mcp-filesystem-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mark3labs/mcp-filesystem-server
- Repository: https://github.com/mark3labs/mcp-filesystem-server

## Overview

MCP Filesystem Server exposes local-file operations and file resources over MCP. The main workflow is an MCP client request routed by the server to filesystem handlers, which validate paths against configured allowed directories before accessing the local filesystem and returning content or results. The README documents the broader operation set; sampled source confirms server registration, CLI startup, path checks, and representative read/search behavior. Some handler-to-helper details are not shown for every operation, so the graph groups the handler suite rather than asserting unobserved call paths.

Main entry points: [`filesystemserver/handler`](https://github.com/mark3labs/mcp-filesystem-server/tree/main/filesystemserver/handler) (Filesystem handlers), [`filesystemserver/server.go`](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/server.go) (MCP server), [`filesystemserver/handler/resources.go`](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/resources.go) (File resources), [`main.go`](https://github.com/mark3labs/mcp-filesystem-server/blob/main/main.go) (Stdio entrypoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP runtime"]
  node_cli["Stdio entrypoint<br/>[main.go]"]
  node_server["MCP server<br/>[server.go]"]
end

subgraph group_access["Access control"]
  node_pathguard["Path validation<br/>[helper.go]"]
  node_allowed["Allowed roots<br/>[handler.go]"]
  node_allowed_list["Allowed directories"]
end

subgraph group_operations["Filesystem operations"]
  node_handler["Filesystem handlers"]
  node_read["Read files<br/>[read_file.go]"]
  node_readmulti["Read multiple"]
  node_write["Write files<br/>[write_file.go]"]
  node_modify["Modify files<br/>[modify_file.go]"]
  node_copy["Copy files<br/>[copy_file.go]"]
  node_move["Move files<br/>[move_file.go]"]
  node_delete["Delete files<br/>[delete_file.go]"]
  node_directories["Directory operations"]
end

subgraph group_discovery["Discovery and resources"]
  node_listing["Directory listing<br/>[list_directory.go]"]
  node_tree["Directory tree<br/>[tree.go]"]
  node_filename_search["Name search<br/>[search_files.go]"]
  node_content_search["Content search"]
  node_metadata["File metadata<br/>[get_file_info.go]"]
  node_resources["File resources<br/>[resources.go]"]
end

node_client(("MCP client"))
node_localfs["Local filesystem"]

node_client -->|"sends requests"| node_server
node_cli -->|"starts"| node_server
node_server -->|"registers handlers"| node_handler
node_handler -->|"validates paths"| node_pathguard
node_handler -.->|"uses configured roots"| node_allowed
node_handler -->|"reads and writes"| node_localfs
node_server -.->|"registers resources"| node_resources
node_handler -->|"returns resource references"| node_resources

click node_cli "https://github.com/mark3labs/mcp-filesystem-server/blob/main/main.go"
click node_server "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/server.go"
click node_handler "https://github.com/mark3labs/mcp-filesystem-server/tree/main/filesystemserver/handler"
click node_pathguard "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/helper.go"
click node_allowed "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/handler.go"
click node_read "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/read_file.go"
click node_readmulti "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/read_multiple_files.go"
click node_write "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/write_file.go"
click node_modify "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/modify_file.go"
click node_copy "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/copy_file.go"
click node_move "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/move_file.go"
click node_delete "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/delete_file.go"
click node_directories "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/create_directory.go"
click node_listing "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/list_directory.go"
click node_tree "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/tree.go"
click node_filename_search "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/search_files.go"
click node_content_search "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/search_within_files.go"
click node_metadata "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/get_file_info.go"
click node_allowed_list "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/list_allowed_directories.go"
click node_resources "https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/resources.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_server,node_client toneBlue
class node_pathguard,node_allowed,node_allowed_list toneAmber
class node_handler,node_read,node_readmulti,node_write,node_modify,node_copy,node_move,node_delete,node_directories toneMint
class node_listing,node_tree,node_filename_search,node_content_search,node_metadata,node_resources toneRose
class node_localfs toneIndigo
```

## Components

### MCP runtime

- [Stdio entrypoint](https://github.com/mark3labs/mcp-filesystem-server/blob/main/main.go): `main.go`
- [MCP server](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/server.go): `filesystemserver/server.go`

### Access control

- [Path validation](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/helper.go): `filesystemserver/handler/helper.go`
- [Allowed roots](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/handler.go): `filesystemserver/handler/handler.go`
- [Allowed directories](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/list_allowed_directories.go): `filesystemserver/handler/list_allowed_directories.go`

### Filesystem operations

- [Filesystem handlers](https://github.com/mark3labs/mcp-filesystem-server/tree/main/filesystemserver/handler): `filesystemserver/handler`
- [Read files](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/read_file.go): `filesystemserver/handler/read_file.go`
- [Read multiple](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/read_multiple_files.go): `filesystemserver/handler/read_multiple_files.go`
- [Write files](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/write_file.go): `filesystemserver/handler/write_file.go`
- [Modify files](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/modify_file.go): `filesystemserver/handler/modify_file.go`
- [Copy files](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/copy_file.go): `filesystemserver/handler/copy_file.go`
- [Move files](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/move_file.go): `filesystemserver/handler/move_file.go`
- [Delete files](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/delete_file.go): `filesystemserver/handler/delete_file.go`
- [Directory operations](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/create_directory.go): `filesystemserver/handler/create_directory.go`

### Discovery and resources

- [Directory listing](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/list_directory.go): `filesystemserver/handler/list_directory.go`
- [Directory tree](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/tree.go): `filesystemserver/handler/tree.go`
- [Name search](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/search_files.go): `filesystemserver/handler/search_files.go`
- [Content search](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/search_within_files.go): `filesystemserver/handler/search_within_files.go`
- [File metadata](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/get_file_info.go): `filesystemserver/handler/get_file_info.go`
- [File resources](https://github.com/mark3labs/mcp-filesystem-server/blob/main/filesystemserver/handler/resources.go): `filesystemserver/handler/resources.go`

### Other components

- **MCP client**
- **Local filesystem**

## Connections

- MCP client → MCP server: sends requests (evidence: `README.md`)
- Stdio entrypoint → MCP server: starts (evidence: `main.go`)
- MCP server → Filesystem handlers: registers handlers (evidence: `filesystemserver/server.go`)
- Filesystem handlers → Path validation: validates paths (evidence: `filesystemserver/handler/search_files.go`)
- Filesystem handlers → Allowed roots: uses configured roots
- Filesystem handlers → Local filesystem: reads and writes (evidence: `filesystemserver/handler/read_file.go`)
- MCP server → File resources: registers resources
- Filesystem handlers → File resources: returns resource references (evidence: `filesystemserver/handler/read_file.go`)
