FileSystem MCP Server

FileSystem MCP Server

Version: 0.1.4 — Last updated: 2026-10-13

Local MCP server for Visual Studio 2022+ that provides code-workspace functionality by giving AI agents selective access to project folders and files

Table of Contents

• 🎯 Target Environment
• Features
• Installation
• Quick Start
• Configuration Options
• Option 1: Config.json File (Simplest - Recommended for Beginners)
• Option 2: Command-Line Arguments (Advanced - For MCP Clients)
• Option 3: Hybrid Approach (Best of Both Worlds)
• Usage
• Command Line Examples
• Available Tools
• Why This Hybrid Approach is Perfect
• Visual Studio 2022+ Debugging
• Visual Studio 2022+ Usage Examples
• Editing Your mcp.json File via GitHub Copilot Chat
• Security
• Error Handling
• Troubleshooting
• MCP Configuration Issues
• Visual Studio 2022+ Debugging
• Common Issues
• Command Line Reference
• Cross-Platform Path Support
• Advanced & Real-World MCP Configuration Examples

---

🎯 Target Environment

This MCP server is optimized for:

• Visual Studio 2022+ development workflows
• Local development environments without complex workspace setups
• Direct folder access scenarios where you need filesystem operations
• Development environments that don't use `.code-workspace` files
• Individual project directories rather than multi-root workspaces

Features

• Directory Traversal: List contents of allowed directories
• File Reading: Read contents of files with allowed extensions
• File Writing: Write text/binary content to files — opt-in via `--allow-write` (disabled by default)
• Directory Validation: Check accessibility of configured directories
• Hybrid Configuration: Command-line arguments (MCP) + config.json fallback (debugging)
• Visual Studio 2022+ Debugging: No-argument startup support
• Cross-Platform Path Support: Automatically handles both Windows (\) and Unix (/) path separators
• Security: Access restricted to explicitly specified directories and file types
• Local Development Focus: Perfect for Visual Studio 2022+ and similar environments

Installation

From PyPI (Recommended for Users)

pip install vs-filesystem-mcp-server

From Source (For Development)

1. Ensure you have Python 3.10+ installed
2. Clone the repository
3. Navigate to the project directory
4. Install dependencies using uv:

   uv sync

Quick Start

1. For MCP usage: Add the corrected configuration to your .mcp.json
2. For debugging: Just press F5 in Visual Studio 2022+ - uses config.json automatically
3. Test your configuration by calling the init() tool first
4. If init() returns errors, check your directory paths and permissions

Configuration Options

Option 1: Config.json File (Simplest - Recommended for Beginners)

The easiest way to get started! Create a config.json file:

For MCP server usage:

• Place config.json in the same folder as your .mcp.json file (usually C:\Users\YourUsername\)

For debugging from source (Visual Studio 2022+):

• Place config.json in the same directory as app.py (D:/Projects/filesystem_server/)

{

"allowed_dirs": [ "C:/Users/YourUsername/Documents/projects", "D:/projects", "D:/Webs" ], "allowed_extensions": [ ".py", ".js", ".ts", ".json", ".md", ".txt", ".yml", ".yaml", ".toml", ".cfg", ".ini", ".cs", ".css", ".scss", ".htm", ".html", ".xml", ".xaml" ], "allow_write": false }

Note: Set "allow_write": true to enable write_file and write_file_binary tools.

MCP Configuration (Installed via pip)

Add this to your .mcp.json file (usually C:\Users\YourUsername\ in VS 2022+):

{

"servers": { "filesystem-server": { "command": "vs-filesystem-mcp-server" } } }

Note: When installed via pip, the command is just vs-filesystem-mcp-server - no path to app.py needed!

MCP Configuration (Running from Source)

If you're developing and running from source code:

{

"servers": { "filesystem-server": { "command": "python", "args": [ "/absolute/path/to/your/project/filesystem_server/app.py" ], "cwd": "/absolute/path/to/your/project/filesystem_server" } } }

Benefits:

• ✅ No command-line arguments needed
• ✅ Perfect for Visual Studio 2022 debugging (just press F5)
• ✅ Works with MCP clients when placed in correct location
• ✅ Easy to edit and modify
• ✅ Great for testing and development

Usage:

# For debugging in Visual Studio 2022:

python app.py # Uses config.json from same directory as app.py

For MCP server usage:

The MCP client automatically finds config.json in the .mcp.json directory

Important Location Notes:

• 🔧 Debugging: config.json goes next to app.py
• 🌐 MCP Server: config.json goes next to .mcp.json
• 📁 Different locations for different use cases!

Option 2: Command-Line Arguments (Advanced - For MCP Clients)

Best for production MCP client configurations where you want everything in one place:

When Installed via pip

{

"servers": { "filesystem-server": { "command": "vs-filesystem-mcp-server", "args": [ "--allowed-dirs", "D:/projects", "D:/Webs", "--allowed-extensions", ".py", ".js", ".ts", ".json", ".md", ".txt" ] } } }

When Running from Source

python app.py --allowed-dirs "D:/projects" "D:/Webs" --allowed-extensions ".py" ".js" ".md"

With write access enabled:

python app.py --allowed-dirs "D:/projects" "D:/Webs" --allowed-extensions ".py" ".js" ".md" --allow-write true

MCP Client Configuration (.mcp.json):

{

"servers": { "filesystem-server": { "command": "python", "args": [ "/absolute/path/to/your/project/filesystem_server/app.py", "--allowed-dirs", "D:/projects", "D:/Webs", "--allowed-extensions", ".py", ".js", ".ts", ".json", ".md", ".txt" ], "cwd": "/absolute/path/to/your/project/filesystem_server" } } }

Benefits:

• ✅ Self-contained configuration
• ✅ No external config files needed
• ✅ Version control friendly
• ✅ Explicit and visible in MCP setup

Option 3: Hybrid Approach (Best of Both Worlds)

The server automatically uses command-line arguments first, then falls back to config.json if no arguments provided.

How it works:

• MCP clients: Use command-line arguments (Option 2)
• Visual Studio debugging: Automatically uses config.json (Option 1)
• Priority: Command-line args override config.json when present

Benefits:

• ✅ Works for both MCP clients and debugging
• ✅ No conflicts between different usage scenarios
• ✅ Flexible and developer-friendly
• ✅ Choose the best option for each situation

Usage

Command Line Examples

# With command line arguments (MCP clients):

python app.py --allowed-dirs "D:/projects" "D:/Webs" --allowed-extensions ".py" ".js" ".md"

Using config.json fallback (Visual Studio 2022+ debugging):

python app.py

Show MCP configuration help:

python app.py --help-mcp

Available Tools

1. init(directory, file_path) - Validates accessibility of configured directories and can optionally list a directory and/or read a file

• directory (optional): Directory path to list contents (can be None)
• file_path (optional): File path to read content (can be None)
• Returns { "message": "OK", "isError": false, ... } if all directories accessible
• Returns error details if any directories are inaccessible
• Shows configuration source (command-line args vs config file)
• Use this to verify your configuration before using other tools

1. list_directory(directory, report_progress=True, batch_size=100) - Lists files and subdirectories in a given directory, with optional progress reporting

• directory: The absolute or relative path to the directory (supports both / and \\ separators)
• report_progress (optional): If True, returns progress information and batch details (default: True)
• batch_size (optional): Number of items to process before reporting progress (default: 100)
• Returns a list of file and directory names if report_progress is False
• Returns a dictionary with contents, progress_info, total_items, and processing_time if report_progress is True
• If an error occurs, returns a dictionary with "error" and "error_message" keys
• No exceptions are raised - all errors are returned as part of the result

1. read_file(file_path) - Reads the content of a specified file as text

• Returns the file content as a string (for text files only)
• Not suitable for binary files (images, audio, etc.)

1. read_file_binary(file_path) - Reads the content of a specified file as base64-encoded binary

• Returns { "content_base64": , "encoding": "base64", "error": False } on success
• Returns an error dict if the file is not allowed or not found
• Suitable for images, audio, and other binary files

1. list_resources(directory=None, report_progress=True, batch_size=100) - Lists all resources (files and directories) in a directory (or all allowed directories) in MCP resource format

• directory (optional): Directory to start from (defaults to all allowed_dirs)
• report_progress (optional): If True, returns progress information and batches (default: True)
• batch_size (optional): Number of resources per progress batch (default: 100)
• Returns a list of resource objects if report_progress is False
• Returns a dictionary with contents, progress_info, total_items, and processing_time if report_progress is True
• Example resource object: json { "id": "D:/projects/example.txt", "type": "file", "name": "example.txt", "path": "D:/projects/example.txt", "metadata": { "size": 1234, "modified": "2025-08-18T12:34:56Z" }, "actions": ["read", "read_binary", "write", "write_binary"] }

1. get_resource(path) - Gets metadata and actions for a specific file or directory

• path: Absolute or relative path to the resource
• Returns a resource object (id, type, name, path, metadata, actions) or an error dict
• For files, includes size and modified time; for directories, includes type and actions
• Does not return file content

1. write_file(file_path, content) - Writes text content to a specified file (requires `--allow-write`)

• file_path: Path to write to (must be within allowed dirs)
• content: Text string to write
• Raises ValueError if write access is disabled, path not allowed, extension not allowed, or IO error
• Overwrites existing file
• Disabled by default — enable with --allow-write flag or "allow_write": true in config.json

1. write_file_binary(file_path, content_base64) - Writes binary content from base64 to file (requires `--allow-write`)

• file_path: Path to write to (must be w