remote-file-server-mcp

An MCP (Model Context Protocol) server that gives any MCP client read access to an SMB/CIFS file share. Connection credentials are passed as environment variables and never appear in tool calls or conversation history.

How It Works

MCP Client  ──(MCP/stdio)──►  file-server-mcp  ──(SMB/CIFS)──►  File Server

The server runs as a subprocess managed by the MCP client. All file access is read-only. SMB packet signing is enforced by default; full encryption is available via an env var.

Tools

| Tool | Arguments | Description | | --------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | list_files | path (optional) | List files and directories at a path. Empty path = share root. Denied filenames are omitted from results. Returns JSON. | | read_file | path | Return text contents of a file. Oversized files return a preview (first N lines) or hard-error if READ_PREVIEW_LINES=0. Binary Office/PDF files are parsed into text when supported. | | get_file_info | path | Return metadata (size, type, timestamps) for a file or directory without reading its contents. | | search_files | pattern, path (optional), max_depth (optional) | Find files by glob pattern (e.g. *.csv). Recurses to max_depth (default 5, max 10) and returns up to 200 matches. |

All paths are relative to the share root (e.g. reports/2024/q1.xlsx).

Security

SMB packet signing is required on all connections (protects against tampering in transit).
Encryption can be enabled via SMB_ENCRYPT=true for end-to-end SMB encryption.
Path traversal is blocked — .. segments are rejected before any SMB call is made.
Sensitive files (.env, *.key, *.pem, id_rsa, *.pfx, *.p12, *.token, .netrc, .htpasswd, keystore files, etc.) are never listed or read.
File size limit prevents reading files that would exceed the context window.
Allowed paths can restrict the server to specific subdirectories only.
Audit logging records every tool call (operation, path, outcome, size) in JSON — never file contents.
Error messages are sanitised — internal hostnames, UNC paths, and credentials are never exposed to the client.

Setup

Option A — pip install

pip install -e /path/to/remote-file-server

Then configure Claude Desktop (see below) with:

"command": "file-server-mcp"

Option B — run from source (no package install)

python3 -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python server.py

Option C — uv

# No install needed — uv resolves dependencies automatically
uv run --directory /path/to/remote-file-server file-server-mcp

Or install into a uv-managed environment:

uv pip install -e /path/to/remote-file-server
uv run file-server-mcp

Option D — Docker

docker build -t file-server-mcp .

See Dockerfile for runtime usage.

MCP Client Configuration

Open your Client config file:

Add an entry under mcpServers.

If using uv (run from source, no prior install):

{
  "mcpServers": {
    "file-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/remote-file-server",
        "file-server-mcp"
      ],
      "env": {
        "SMB_HOST": "192.168.1.100",
        "SMB_SHARE": "my_share",
        "SMB_USERNAME": "my_user",
        "SMB_PASSWORD": "my_password"
      }
    }
  }
}

If installed via pip/uv pip (console script entry point):

{
  "mcpServers": {
    "file-server": {
      "command": "file-server-mcp",
      "env": {
        "SMB_HOST": "192.168.1.100",
        "SMB_SHARE": "my_share",
        "SMB_USERNAME": "my_user",
        "SMB_PASSWORD": "my_password",
        "SMB_PORT": "445",
        "ALLOWED_PATHS": "reports,finance",
        "AUDIT_LOG_PATH": "/var/log/file-server-mcp/audit.jsonl"
      }
    }
  }
}

Security note: The config file contains credentials. Ensure it is only readable by your user account (chmod 600 on macOS/Linux).

Restart Claude Desktop after saving.

Connecting to Multiple Servers

Add a separate entry for each server with a unique key:

{
  "mcpServers": {
    "file-server-prod": {
      "command": "file-server-mcp",
      "env": {
        "SMB_HOST": "10.0.0.10",
        "SMB_SHARE": "Production",
        "...": "..."
      }
    },
    "file-server-dev": {
      "command": "file-server-mcp",
      "env": {
        "SMB_HOST": "10.0.0.20",
        "SMB_SHARE": "Development",
        "...": "..."
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | | -------------------- | -------- | ------- | --------------------------------------------------------------------- | | SMB_HOST | Yes | — | IP address or hostname of the SMB server | | SMB_SHARE | Yes | — | Share name on the server | | SMB_USERNAME | Yes | — | Username for SMB authentication | | SMB_PASSWORD | Yes | — | Password for SMB authentication | | SMB_PORT | No | 445 | SMB port | | SMB_ENCRYPT | No | false | Set to true to enable SMB encryption (requires server support) | | MAX_FILE_SIZE_MB | No | 10 | Maximum file size in MB that read_file will read | | READ_PREVIEW_LINES | No | 100 | Lines to return for oversized files. Set to 0 to hard-error instead | | ALLOWED_PATHS | No | — | Comma-separated subdirectory allowlist, e.g. reports,finance/2024 | | AUDIT_LOG_PATH | No | stdout | File path for JSON audit logs. Falls back to stdout if unset |

Requirements

Python 3.11+
Network access to the SMB server (port 445 by default)
SMB credentials with read permissions on the share

MCP Servers