mcp-smb

The MCP SMB Server exposes access to SMB/CIFS shares or local filesystem paths through MCP as a runtime service. It enforces native filesystem permissions by delegating authorization to the underlying OS or SMB server, rather than implementing its own policy engine. This makes it suitable for agents that need on-demand, permission-correct file access without pre-indexing or data duplication. The server communicates over standard input/output, which makes it friendly for integration with IDEs and agent frameworks that use the MCP runtime protocol.

Available MCP tools include list_directory and read_file. list_directory returns the contents of a given path, helping an agent discover what files are available and which subdirectories exist. read_file reads a bounded portion of a file, returning a chunk up to max_bytes (default 8192). These tools are designed to be small, stateless operations that rely on real-time filesystem permissions, ensuring revocation and access control are honored by the underlying filesystem.

Prerequisites:

• Go 1.24 or later
• Access to a build environment with internet (for module download)
• For SMB mode: access to an SMB/CIFS server; for local mode: appropriate filesystem permissions

Install steps:

1. Clone the repository

git clone <repository-url>
cd mcp-smb-server

2. Build the server binary

go build -o mcp-smb-server ./cmd/server

3. Run the server

• SMB mode (with environment variables configured for SMB):

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 a config file):

./mcp-smb-server --config config.yaml

Environment variables:

• MCP_MODE controls the backend mode (smb or local).
• SMB_ADDR, SMB_SHARE, SMB_AUTH, SMB_USER, SMB_PASSWORD are needed for SMB mode; do not store credentials in config files.

Common issues:

• Ensure the network path and SMB credentials are correct; the server does not cache credentials.
• Local mode requires the process to have filesystem permissions to read the configured base paths.
• If running behind a firewall, ensure the SMB port is reachable or use a local path fallback.

Configuration tips:

• Use the Quick Start examples in the README to bootstrap either SMB or local mode.
• Remember that this server enforces native OS/SMB permissions; access will fail if the underlying system denies it.