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

![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)
![FastMCP](https://img.shields.io/badge/FastMCP-Latest-orange.svg)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)

---

# 📖 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

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

cd local-filesystem-mcp
```

Create a virtual environment

```bash
python -m venv .venv
```

Activate it

Windows

```powershell
.venv\Scripts\activate
```

Linux / macOS

```bash
source .venv/bin/activate
```

Install dependencies

```bash
pip install -r requirements.txt
```

---

# ▶ Running the Server

Simply run

```bash
python server.py
```

The default server starts on

```
http://localhost:8000/mcp
```

using the **Streamable HTTP** transport.

---

# 🧪 Testing with MCP Inspector

Launch the inspector

```bash
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

```bash
python server.py
```

Expose port 8000

```bash
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

```json
{
  "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

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

Useful for reducing multiple MCP calls.

---

## 📜 read_lines_tool

Reads only selected lines.

Example

```json
{
    "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! 🚀