🚀 Local Filesystem MCP Server

A production-ready Model Context Protocol (MCP) server that allows AI assistants such as ChatGPT, Claude, Cursor, Perplexity, VS Code, and other MCP-compatible clients to securely browse, search, inspect, and understand local projects.

📖 Overview

Large Language Models perform significantly better when they have structured access to a project's source code instead of relying on manually copied snippets.

This project exposes your local filesystem through the Model Context Protocol (MCP) using FastMCP and Streamable HTTP, enabling AI assistants to:

• Browse project directories

• Read source code

• Search files

• Search text across projects

• Build project context

• Generate project statistics

• Locate definitions

• Find references

• Read multiple files simultaneously

• Produce project outlines

Instead of uploading your project manually, the AI can explore it through dedicated MCP tools.

✨ Features

✅ List directories

✅ Read files

✅ Read multiple files

✅ Read selected line ranges

✅ Read entire projects

✅ Build project context

✅ Generate project tree

✅ Search filenames

✅ Search text inside files

✅ Generate project statistics

✅ Extract code outline

✅ Locate symbol definitions

✅ Find symbol references

✅ Fast recursive traversal

✅ Ignore build folders automatically

✅ UTF-8 safe reading

✅ Streamable HTTP transport

✅ Works with public tunnels (ngrok / Cloudflare)

🏗 Architecture

+----------------------+
| AI Client            |
| ChatGPT              |
| Claude               |
| Cursor               |
| VS Code              |
| Perplexity           |
+----------+-----------+
|
| MCP
|
v

+----------------------+
| FastMCP Server |
| server.py |
+----------+-----------+
|
|
+------------------------------+
| |
v v

Filesystem Tool Layer Security Layer

|
v

+----------------------+
| Local File System |
+----------------------+

The AI client communicates with the MCP server using Streamable HTTP, and each tool performs a specific filesystem operation.

📂 Project Structure

MCP_PROJECT/

├── logs/
│
├── tools/
│ ├── code_outline.py
│ ├── file_tree.py
│ ├── find_references.py
│ ├── list_directory.py
│ ├── locate_definition.py
│ ├── metadata.py
│ ├── project_context.py
│ ├── project_statistics.py
│ ├── read_directory.py
│ ├── read_files.py
│ ├── read_lines.py
│ ├── read_multiple_files.py
│ └── search_files.py
│
├── config.py
├── filesystem.py
├── security.py
├── server.py
├── requirements.txt
└── README.md

🚀 Installation

Clone the repository

git clone https://github.com/<your-username>/local-filesystem-mcp.git

cd local-filesystem-mcp

Create a virtual environment

python -m venv .venv

Activate it

Windows

.venv\Scripts\activate

Linux / macOS

source .venv/bin/activate

Install dependencies

pip install -r requirements.txt

▶ Running the Server

Simply run

python server.py

The default server starts on

http://localhost:8000/mcp

using the Streamable HTTP transport.

🧪 Testing with MCP Inspector

Launch the inspector

mcp dev server.py

Open

http://localhost:6274

Use

Transport

Streamable HTTP

URL

http://localhost:8000/mcp

Press Connect.

If successful, all registered tools will appear automatically.

🌍 Exposing the Server Publicly

Although the server runs locally, it can be securely exposed over the internet using tunneling services.

Supported options include:

• ngrok

• Cloudflare Tunnel

• Tailscale Funnel

• Reverse Proxy (Nginx/Caddy)

Using ngrok

Start your MCP server

python server.py

Expose port 8000

ngrok http 8000

Example output

Forwarding

https://abcd-1234.ngrok-free.app

↓

http://localhost:8000

Your public MCP endpoint becomes

https://abcd-1234.ngrok-free.app/mcp

This endpoint can now be added to any MCP-compatible client.

🔧 Available Tools

The server exposes multiple MCP tools for filesystem exploration and project understanding.

Related MCP server: folder-mcp

📁 list_directory

Lists files and folders inside a directory.

Parameters

Example

{
  "path":"D:/Projects"
}

Returns

• folders

• files

• relative paths

📄 read_file_tool

Reads an entire text file.

Parameters

Returns

Complete file contents

📑 read_multiple_files

Reads multiple files in one request.

Example

{
  "paths":[
      "server.py",
      "filesystem.py",
      "README.md"
  ]
}

Useful for reducing multiple MCP calls.

📜 read_lines_tool

Reads only selected lines.

Example

{
    "path":"server.py",
    "start":100,
    "end":140
}

Ideal for debugging specific code sections.

📂 read_directory

Recursively scans an entire directory and returns supported source files.

Automatically ignores

• node_modules

• build

• dist

• venv

• pycache

• .git

Supported languages include

• Python

• JavaScript

• TypeScript

• Java

• C/C++

• C#

• Go

• Rust

• HTML

• CSS

• SQL

• JSON

• YAML

• XML

• Markdown

🌳 file_tree

Generates a visual directory tree.

Example

project/

├── server.py
├── requirements.txt
├── tools
│   ├── read_file.py
│   ├── metadata.py
│   └── project_context.py
└── frontend

Useful before exploring a large repository.

🔍 search_files

Searches filenames recursively.

Example

invoice

Returns

invoice.py

invoice_parser.py

invoice_service.py

🔎 search_text

Searches text inside source code.

Example

FastMCP

Returns

server.py : line 18

filesystem.py : line 62

config.py : line 11

🧠 project_context

Builds an optimized context for Large Language Models.

Priority files

• README.md

• package.json

• requirements.txt

• pyproject.toml

• Dockerfile

• .gitignore

are loaded first.

Then the remaining source code is loaded.

This dramatically improves repository understanding.

📊 project_statistics

Returns project metrics.

Includes

• total files

• source files

• folders

• languages

• lines of code

• largest files

Useful for repository analysis.

📋 code_outline

Extracts

• classes

• functions

• methods

without returning the full file.

Ideal for navigating large source files.

🎯 locate_definition

Locates where a function or class is defined.

Example

search

↓

search_text()

Returns

filesystem.py

Line 281

🔗 find_references

Finds every reference to a symbol.

Example

project_context

Returns

server.py

tools/project_context.py

README.md

Excellent for code navigation.

💡 Typical AI Workflow

Rather than immediately reading every source file, an AI assistant should follow this workflow.

file_tree()

↓

project_statistics()

↓

project_context()

↓

search_files()

↓

read_file()

↓

read_lines()

↓

find_references()

↓

locate_definition()

This minimizes unnecessary data transfer while maximizing repository understanding.

🔐 Security

The server is designed to expose only the directories you explicitly request.

Additional safeguards include

• UTF-8 safe reading

• ignored system folders

• ignored virtual environments

• ignored build artifacts

• configurable transport security

• optional DNS rebinding protection

• Streamable HTTP transport

For production deployments, enable DNS rebinding protection and configure allowed hosts appropriately.

⚙ Configuration

Default configuration

These values can be customized in server.py.

🛣 Roadmap

Planned improvements include

• Git integration

• Symbol indexing

• AST-based code navigation

• Dependency graph generation

• Call graph visualization

• Semantic code search

• Repository summarization

• Incremental indexing

• Embedding support

• Vector search

• Workspace caching

🤝 Contributing

Contributions are welcome.

You can contribute by

• Reporting bugs

• Suggesting features

• Improving documentation

• Optimizing filesystem traversal

• Adding new MCP tools

• Improving cross-platform compatibility

Please read CONTRIBUTING.md before submitting pull requests.

📄 License

This project is licensed under the MIT License.

See the LICENSE file for details.

⭐ Support

If you find this project useful, consider giving it a ⭐ on GitHub.

It helps others discover the project and motivates future development.

👨‍💻 Author

Developed as part of an internship project to provide secure, extensible, and AI-friendly access to local filesystems through the Model Context Protocol (MCP).

Happy Coding! 🚀