🚀 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.

---

📁 list_directory

Lists files and folders inside a directory.

Parameters

Name	Type	Description
path	string	Directory path

Example

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

Returns

• folders
• files
• relative paths

---

📄 read_file_tool

Reads an entire text file.

Parameters

Name	Type
path	string

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

Setting	Value
Host	0.0.0.0
Port	8000
Endpoint	/mcp
Transport	Streamable HTTP

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! 🚀