FileSystem MCP Server

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:

   bash

   Copy

   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

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

3. 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.)

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

   • Returns { "content_base64": <base64 string>, "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