How to Build an MCP Server for the Filesystem

uv init --python 3.11 fs-tools && cd fs-tools
uv add "mcp[cli]>=2.0.0"

import os
from pathlib import Path

# The sandbox root. Nothing outside this directory is ever readable or writable.
ROOT = Path(os.environ.get("MCP_FS_ROOT", ".")).resolve()


def _safe(path: str) -> Path:
    """Resolve `path` against ROOT and refuse anything that escapes the sandbox."""
    candidate = (ROOT / path).resolve()
    if candidate != ROOT and ROOT not in candidate.parents:
        raise ValueError(f"path escapes the sandbox root: {path}")
    return candidate

from typing_extensions import TypedDict

from mcp.server.mcpserver import MCPServer

mcp = MCPServer(name="fs-tools", version="1.0.0")


class Entry(TypedDict):
    name: str
    type: str  # "file" or "dir"
    size: int


class WriteResult(TypedDict):
    path: str
    bytes_written: int


@mcp.tool()
def list_directory(path: str = ".") -> list[Entry]:
    """List the entries in a directory inside the sandbox."""
    target = _safe(path)
    entries: list[Entry] = []
    for child in sorted(target.iterdir()):
        entries.append(
            Entry(
                name=child.name,
                type="dir" if child.is_dir() else "file",
                size=child.stat().st_size,
            )
        )
    return entries


@mcp.tool()
def read_file(path: str) -> str:
    """Read a UTF-8 text file inside the sandbox and return its contents."""
    return _safe(path).read_text(encoding="utf-8")


@mcp.tool()
def write_file(path: str, content: str) -> WriteResult:
    """Write UTF-8 text to a file inside the sandbox, creating parents as needed."""
    target = _safe(path)
    target.parent.mkdir(parents=True, exist_ok=True)
    written = target.write_text(content, encoding="utf-8")
    return WriteResult(path=str(target.relative_to(ROOT)), bytes_written=written)

@mcp.resource("info://root")
def sandbox_root() -> str:
    """The absolute path the server is sandboxed to."""
    return f"fs-tools v1.0.0 sandboxed to {ROOT}"


if __name__ == "__main__":
    mcp.run("stdio")

"""End-to-end test: spawn server.py over stdio, connect a client, exercise it."""
import asyncio
import os
import tempfile

from mcp import ClientSession, StdioServerParameters, stdio_client


async def main() -> None:
    sandbox = tempfile.mkdtemp(prefix="fs-sandbox-")
    env = {**os.environ, "MCP_FS_ROOT": sandbox}
    params = StdioServerParameters(
        command="uv", args=["run", "python", "server.py"], env=env
    )
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            names = sorted(t.name for t in tools.tools)
            assert names == ["list_directory", "read_file", "write_file"], names

            # write_file returns a typed WriteResult -> structured_content
            w = await session.call_tool(
                "write_file", {"path": "notes/todo.txt", "content": "ship the post"}
            )
            assert w.structured_content == {
                "path": "notes/todo.txt",
                "bytes_written": 13,
            }, w.structured_content

            # read_file returns a str -> wrapped as {"result": ...}
            r = await session.call_tool("read_file", {"path": "notes/todo.txt"})
            assert r.structured_content["result"] == "ship the post", r.structured_content

            # list_directory returns a list -> wrapped as {"result": [...]}
            ls = await session.call_tool("list_directory", {"path": "notes"})
            assert ls.structured_content["result"] == [
                {"name": "todo.txt", "type": "file", "size": 13}
            ], ls.structured_content

            # path traversal is refused: the tool call reports an error
            escape = await session.call_tool("read_file", {"path": "../../etc/passwd"})
            assert escape.is_error, "traversal should have been rejected"
            assert "escapes the sandbox" in escape.content[0].text, escape.content

    print("ALL CHECKS PASSED")


if __name__ == "__main__":
    asyncio.run(main())

uv run python test_server.py
# ALL CHECKS PASSED

{
  "mcpServers": {
    "fs-tools": {
      "command": "uv",
      "args": ["--directory", "/abs/path/to/fs-tools", "run", "python", "server.py"],
      "env": { "MCP_FS_ROOT": "/abs/path/to/the/folder/to/expose" }
    }
  }
}