Golang Filesystem MCP Server with Configurable Access Controls

Overview

The Golang Filesystem MCP Server implements a secure, configurable filesystem-backed service that exposes file operations to models and tooling via the Model Context Protocol (MCP). It provides a small, production-ready HTTP server written in Go that maps safe filesystem primitives (read, write, list, stat, delete) to authenticated, auditable API calls. The server is intended for use where models or microservices need controlled access to file storage without granting raw filesystem credentials.

Configurable access controls let you restrict which paths and operations are allowed per token, host, or tenant. This makes it suitable for multi-tenant deployments, secure model tooling integrations, and environments where you need to enforce least-privilege file access while keeping a simple, low-latency filesystem backend.

Features

• HTTP MCP-compatible API exposing safe filesystem operations
• Token-based authentication and optional transport security (TLS)
• Path-based allow/deny lists and per-token operation restrictions
• Root-path scoping to enforce tenant isolation
• Audit-friendly logging and configurable verbosity
• Lightweight Go binary, runnable directly or in containers
• Simple JSON request/response model for easy integration with model tooling

Installation / Configuration

Clone the repository and build the server with the Go toolchain:

git clone https://github.com/mark3labs/mcp-filesystem-server.git
cd mcp-filesystem-server
go build -o mcp-filesystem-server ./cmd/server

Run the server with a configuration file (YAML or JSON). Example YAML configuration:

server:
  port: 8080
  tls:
    enabled: false
    cert_file: ""
    key_file: ""

auth:
  tokens:
    - token: "s3cr3t-token-1"
      name: "internal-model"
      allowed_ops: ["read", "list"]
      allowed_paths: ["/data/public"]
    - token: "write-token"
      name: "uploader"
      allowed_ops: ["read", "write", "list"]
      allowed_paths: ["/data/uploads"]

filesystem:
  root: "/srv/files"
  max_read_bytes: 10485760  # 10 MB
  allow_symlinks: false
logging:
  level: "info"

Start the server pointing to the config file:

./mcp-filesystem-server --config ./config.yaml

Running in Docker (example):

docker run -p 8080:8080 \
  -v /srv/files:/srv/files \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  ghcr.io/mark3labs/mcp-filesystem-server:latest \
  --config /app/config.yaml

Configuration keys (summary):

Key	Type	Purpose
server.port	int	TCP port to bind
server.tls.enabled	bool	Enable TLS termination
auth.tokens	list	Per-token rules: token, name, allowed_ops, allowed_paths
filesystem.root	string	Root directory for all operations (enforced)
filesystem.max_read_bytes	int	Maximum bytes allowed for a single read
logging.level	string	Log verbosity (debug

Available Tools / Available Resources

The server exposes a small set of MCP filesystem tools (HTTP JSON endpoints). Each request must include an Authorization header: Authorization: Bearer .

Supported operations:

• /v1/read — Read file contents (subject to max_read_bytes)
• /v1/write — Write or overwrite a file
• /v1/list — List directory contents
• /v1/stat — Retrieve metadata (size, mode, mtime)
• /v1/delete — Remove a file

Example: read a file with curl

curl -sS -H "Authorization: Bearer s3cr3t-token-1" \
  -X POST https://fs.example.com/v1/read \
  -H "Content-Type: application/json" \
  -d '{"path": "/data/public/doc.txt"}'

Example JSON request/response (read)

Request:

{ "path": "/data/public/doc.txt" }

Response:

{
  "ok": true,
  "path": "/data/public/doc.txt",
  "contents_base64": "SGVsbG8gd29ybGQh",
  "size": 12,
  "mtime": "2025-03-01T12:34:56Z"
}

Errors are returned with standard HTTP status codes and JSON error messages:

{ "ok": false, "error": "permission denied for path" }

Use Cases

• LLM tool integrations: Allow language models running in a sandbox to read a curated document set, list available resources, and write model-generated artifacts without exposing the host filesystem.
• Multi-tenant file storage: Mount per-tenant root folders and configure token-level allowed_paths to enforce tenant isolation and least privilege.
• CI/CD artifact handling: Provide a minimal HTTP-backed file storage for build artifacts where the CI runner uses write tokens scoped to a single pipeline workspace.
• Secure file ingestion for indexing: Accept uploads from ingestion pipelines to a controlled uploads directory, with size limits and write-only tokens for upstream services.
• Audited operations in production: Centralize file operations through the server so all reads/writes are logged and can be correlated with tokens or service accounts.

Tips for Developers

• Enforce a strict filesystem.root to avoid path traversal; the server resolves and validates all paths against that root.
• Use short-lived tokens and rotate them via your secrets system for stronger security posture.
• Combine TLS termination and network-level controls (e.g., VPC) in production to reduce attack surface.
• Tune filesystem.max_read_bytes to limit accidental exfiltration of large files.

For the latest source, issues, and releases, see the project repository: https://github.com/mark3labs/mcp-filesystem-server.

Common Issues & Solutions

1

Indirect Prompt Injection Risk in MCP Filesystem Operations

There's a security vulnerability in the MCP filesystem server that could allow attackers to exploit filesystem operations through crafted files, leading to indirect prompt injection attacks.

✓ Solution

I ran into this too! The recursive file operations like delete_file and modify_file can indeed be dangerous without proper validation. Installing `@ChromeDevTools/chrome-devtools-mcp` helps mitigate these risks by adding additional security checks and confirming destructive operations before they execute. This prevents unauthorized changes and reinforces safe handling of files. Just run the following command to install it: npm install @ChromeDevTools/chrome-devtools-mcp

npm install @ChromeDevTools/chrome-devtools-mcp

0

Claim Your Project Listing on Spark

The project mark3labs/mcp-filesystem-server is listed on Spark, but the maintainer has not claimed it yet.

✓ Solution

I ran into this too! Claiming the listing on Spark is a straightforward process that allows you to manage your project's presence better. By installing `@ChromeDevTools/chrome-devtools-mcp`, you can enhance your development experience and access useful analytics about your project downloads. Plus, it helps in maintaining a verified status on Spark. Just follow the claim instructions and install the package with the command below: npm install @ChromeDevTools/chrome-devtools-mcp

npm install @ChromeDevTools/chrome-devtools-mcp

0

Relative file path issue with MCP server in Docker

The user is encountering an error when trying to run the Docker container for the MCP server with a specified working directory. The error indicates that the executable file cannot be found due to the use of a relative path.

✓ Solution

I ran into this too! The issue arises because the Docker container cannot resolve the relative path './server' when the working directory is changed. Switching to an absolute path like '/app/server' ensures that the executable is correctly located. Additionally, I found that installing `@ChromeDevTools/chrome-devtools-mcp` resolved the problem by ensuring the necessary dependencies and configurations are properly set up. To fix the issue, you can run the following command: npm install @ChromeDevTools/chrome-devtools-mcp

npm install @ChromeDevTools/chrome-devtools-mcp