Skip to main content
Glama
Saikiran2412

File System MCP Server

by Saikiran2412
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

File System MCP Server

An MCP (Model Context Protocol) server that exposes filesystem operations — listing directories, reading, writing, and searching files — as tools an LLM can discover and invoke at runtime. Built as a learning project to understand MCP's architecture from the ground up, using the low-level Server API (raw JSON Schemas, not the decorator-based FastMCP shortcut).

What this project demonstrates

  • How an MCP server advertises capabilities to a host via tools/list, and how the host routes an LLM's tool-call decision back via tools/call

  • Why tool descriptions are prompt engineering, not documentation — the LLM only ever sees the JSON Schema, never your source code

  • Defensive server design: path sandboxing, input validation, structured error responses instead of crashes, and result truncation for large outputs

  • The read-only vs. destructive vs. idempotent distinction MCP tool annotations are meant to capture

Related MCP server: MCP Server

Architecture

Host (Claude Desktop / MCP Inspector / any MCP client)
   │
   │  tools/list  →  server responds with schemas for all 4 tools
   │  tools/call  →  host sends {name, arguments}, server executes and
   │                 returns a result
   ▼
This server (stdio transport)
   │
   ▼
sandbox/  (all file operations are confined to this directory)

The server never calls the LLM and the LLM never calls the server directly — the host sits in between, using the schemas below to decide when and how to invoke each tool.

Tools

Tool

Type

Description

read_file

read-only

Reads and returns the full text content of a file

list_directory

read-only

Lists files and folders in a directory (folders suffixed with /)

write_file

destructive

Writes text to a file; refuses to overwrite existing files unless overwrite: true

search_files

read-only

Recursively searches by filename glob pattern and/or file content, capped at 100 results

All tools operate relative to a sandboxed root directory (./sandbox) — paths are resolved and verified to stay inside that boundary before any filesystem access happens, blocking path-traversal attempts like ../../etc/passwd.

Setup

uv sync

Running

With the MCP Inspector (recommended for development — shows raw protocol traffic and lets you call tools manually):

npx @modelcontextprotocol/inspector uv run main.py

Open the URL it prints, click Connect, then Tools → List Tools to see all four schemas, and run any tool directly from the form UI.

As a server for an MCP host (e.g. Claude Desktop), add to your host's MCP config:

{
  "mcpServers": {
    "fs-mcp-server": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/fs-mcp-server", "main.py"]
    }
  }
}

Security design

  • Sandboxing (resolve_safe_path): every incoming path is joined onto the sandbox root, resolved to an absolute path, and checked with Path.is_relative_to() to confirm it didn't escape via .. segments. Rejected paths raise a caught ValueError, never crash the server.

  • Overwrite protection: write_file will not silently clobber an existing file — it requires an explicit overwrite: true argument.

  • Result truncation: search_files caps output at 100 matches and notes when results were truncated, rather than risking an enormous response.

  • Graceful failure everywhere: missing arguments, non-existent paths, wrong path types (file vs. directory), and unreadable/binary files all return a structured error message to the caller instead of raising an uncaught exception.

Known limitations / next steps

  • Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are not yet set explicitly — without them, hosts may apply incorrect defaults (e.g. flagging a read-only tool as destructive).

  • Currently stdio transport only; could be extended to streamable HTTP for remote deployment.

  • search_files content search reads full file contents into memory per candidate file — fine for a learning project, would need streaming for very large files in production.

Stack

Python, mcp (official Anthropic SDK), uv for dependency management.

Available Tools

2 tools
list_directoryA

Lists the contents of a directory within the sandbox. Returns file and folder names, with folders marked so they can be told apart from files. If no path is given, lists the sandbox root directory.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoRelative path to a subdirectory within the sandbox. Optional — defaults to the sandbox root if omitted.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description clearly states the operation, return type (file/folder names with folders marked), and default behavior when path is omitted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler, each sentence adds distinct value: first states function and return, second states default path.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description provides sufficient information about behavior and return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and already describes the default behavior. The description adds only that folders are marked, which is marginal additional value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'lists' and resource 'directory within the sandbox', and distinguishes from sibling tool 'read_file' by mentioning it returns names and marks folders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing directory contents, and the sibling tool 'read_file' provides clear context for when to use this tool, though no explicit exclusions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_fileA

Reads and returns the full text content of a file. The path must be relative to the server's sandboxed root directory. Returns an error if the file does not exist, is not readable as text, or resolves outside the sandbox.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesRelative path to the file, e.g. 'notes/todo.txt'

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses that it reads text content, returns errors for missing files, non-text content, or sandbox escape. Lacks details on file size limits or encoding, but adequate for simple tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, each sentence adds essential information. No wasted words. Concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter, no output schema, and no annotations, the description covers purpose, constraints, and error conditions. Missing info on file size limits or encoding, but overall complete given complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with description of 'path' parameter. Description adds value by stating path must be relative to sandbox root, which is not in schema description. Provides example path format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads and returns full text content of a file, with specific verb+resource. It distinguishes from sibling tool 'list_directory' which lists directory contents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: path must be relative to sandbox root, and error conditions for non-existence, non-readable text, or sandbox escape. Implicitly guides when to use, but does not explicitly contrast with alternatives beyond the sandbox constraint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observedlist_directory
    • First observedread_file
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: one reads file content and the other lists directory contents. There is no overlap or ambiguity.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern (read_file, list_directory), making them predictable and easy to understand.

Tool Count2/5

Only 2 tools for a file system server is too few. Typical file operations like write, delete, or copy are missing, making the scope feel thin.

Completeness2/5

The server lacks essential file operations (create, update, delete, copy, move) and advanced directory listing features. The surface is significantly incomplete for a file system server.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Filesys

    YothisisTroy
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    A Filesystem MCP server that allows an LLM to read and list files from a specified directory on your local machine through the Model Context Protocol.
    2
    -

  • local-mcp

    fan-67
    A
    license
    Not graded
    quality
    C
    maintenance
    A lightweight, stdio-based MCP server enabling AI assistants to perform local file system operations like reading, writing, searching, and executing commands.
    5,122
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Saikiran2412/file_system_mcp_server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server