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:

```bash