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
Recommend Servers
View AllPlaywright MCP server