MCP SMB Server

A runtime file-access gateway for AI agents using the Model Context Protocol (MCP).

This project allows AI agents to access SMB/CIFS shares or local filesystem paths at runtime, while preserving native filesystem permission enforcement.

If the underlying system cannot read a file, the agent cannot read it either.

---

What this project is not

• ❌ No filesystem indexing
• ❌ No embeddings or vector databases
• ❌ No data sync or pre-copy
• ❌ No permission bypass
• ❌ No IAM or policy engine

---

What it does

• ✅ Exposes files only at access time
• ✅ Relies on native SMB / OS permission enforcement
• ✅ Uses MCP as a runtime control plane
• ✅ Supports SMB and local filesystem backends
• ✅ Communicates over stdio (VS Code / agent friendly)

---

Why this exists

Most AI file integrations follow this pattern:

Filesystem → Sync → Index → Embed → Agent

This breaks permission models and makes revocation impossible.

This project instead does:

Agent → MCP → Runtime filesystem access → Native permission check

No indexing. No duplication. No policy reimplementation.

---

Backends

Local mode

• Accesses local directories
• Restricted to configured base paths
• Uses OS permissions

SMB mode

• Accesses SMB/CIFS shares
• Authorization handled by the SMB server
• No credentials stored in config files

---

Available MCP tools

list_directory

Lists files and directories at a given path.

Arguments

• path (string, required)

---

read_file

Reads a bounded portion of a file.

Arguments

• path (string, required)
• max_bytes (number, optional, default: 8192)

---

Configuration

Configuration is process-level, loaded once at startup.

For detailed configuration examples, see the Configuration Guide.

Quick Start:

# SMB mode with environment variables
export MCP_MODE=smb
export SMB_ADDR=localhost:445
export SMB_SHARE=finance
export SMB_AUTH=ntlm
export SMB_USER=alice
export SMB_PASSWORD=your_password
./mcp-smb-server

# Local mode with config file
./mcp-smb-server --config config.yaml

---

Architecture

MCP → FileBackend → { Local | SMB }

The server does not make authorization decisions.
All access decisions are made by the underlying filesystem or SMB server.

---

What this project intentionally does not include

• Centralized policy management
• Approval workflows
• Cross-backend access rules
• Audit aggregation

This project defines a minimal, correct execution boundary on top of which higher-level governance can be built.

---

Installation

Prerequisites

• Go 1.24 or later
• For SMB mode: Access to an SMB/CIFS server
• For local mode: Appropriate filesystem permissions

Build

git clone <repository-url>
cd mcp-smb-server
go build -o mcp-smb-server ./cmd/server

---

License

Apache License 2.0