Filesystem MCP Server Documentation¶

Overview¶

The Filesystem MCP Server provides secure, controlled access to local file systems for AI assistants through the Model Context Protocol (MCP). Built on the proven mcp-filesystem-server foundation, it offers comprehensive file and directory operations while maintaining strict security through configurable allowed directories.

Quick Start¶

Installation & Deployment¶

The filesystem template uses stdio transport and runs interactively rather than as a persistent deployment.

# Interactive mode (recommended)
mcpp interactive
mcpp> config filesystem allowed_dirs="/tmp /home/user/documents"
mcpp> tools filesystem
mcpp> call filesystem list_directory '{"path": "/tmp"}'

# Direct tool execution
mcpp run-tool filesystem list_directory \
  --config allowed_dirs="/tmp /home/user/documents" \
  '{"path": "/tmp"}'

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Configuration¶

Required Configuration¶

allowed_dirs (required): Space-separated list of allowed directories
Environment: ALLOWED_DIRS
Example: "/home/user/documents /tmp/workspace"
Security: Only these directories and subdirectories are accessible

Optional Configuration¶

log_level: Logging verbosity (DEBUG, INFO, WARNING, ERROR)
Environment: LOG_LEVEL
Default: INFO

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Configuration Examples¶

# Environment variables
export ALLOWED_DIRS="/home/user/documents /tmp"
export LOG_LEVEL="DEBUG"

# JSON config file
echo '{"allowed_dirs": "/tmp /home/user/documents", "log_level": "INFO"}' > config.json
mcpp run-tool filesystem list_directory --config-file config.json '{"path": "/tmp"}'

# CLI configuration
mcpp run-tool filesystem list_directory \
  --config allowed_dirs="/tmp /home/user/documents" \
  --config log_level="DEBUG" \
  '{"path": "/tmp"}'

Directory Operations¶

`list_allowed_directories`¶

List all configured allowed directories.

Parameters: None Returns: Array of allowed directory paths

Example:

mcpp> call filesystem list_allowed_directories '{}'

`list_directory`¶

List contents of a directory.

Parameters: - path (string, required): Directory path to list

Returns: Array of files and subdirectories with metadata

Example:

mcpp> call filesystem list_directory '{"path": "/tmp"}'

`tree`¶

Display directory structure as a tree.

Parameters: - path (string, required): Root directory path - max_depth (integer, optional): Maximum depth to traverse

Returns: Tree structure representation

Example:

mcpp> call filesystem tree '{"path": "/tmp", "max_depth": 3}'

`create_directory`¶

Create a new directory.

Parameters: - path (string, required): Directory path to create

Returns: Success confirmation

Example:

mcpp> call filesystem create_directory '{"path": "/tmp/new-folder"}'

File Operations¶

`read_file`¶

Read contents of a file.

Parameters: - path (string, required): File path to read

Returns: File contents as string

Example:

mcpp> call filesystem read_file '{"path": "/tmp/example.txt"}'

`read_multiple_files`¶

Read multiple files efficiently in a single operation.

Parameters: - paths (array, required): Array of file paths to read

Returns: Array of file contents with metadata

Example:

mcpp> call filesystem read_multiple_files '{"paths": ["/tmp/file1.txt", "/tmp/file2.txt"]}'

`write_file`¶

Create or overwrite a file with content.

Parameters: - path (string, required): File path to write - content (string, required): Content to write

Returns: Success confirmation

Example:

mcpp> call filesystem write_file '{"path": "/tmp/output.txt", "content": "Hello World!"}'

`modify_file`¶

Update specific parts of an existing file.

Parameters: - path (string, required): File path to modify - content (string, required): New content for the file

Returns: Success confirmation with modification details

Example:

mcpp> call filesystem modify_file '{"path": "/tmp/existing.txt", "content": "Updated content"}'

`copy_file`¶

Copy a file to a new location.

Parameters: - source (string, required): Source file path - destination (string, required): Destination file path

Returns: Success confirmation

Example:

mcpp> call filesystem copy_file '{"source": "/tmp/source.txt", "destination": "/tmp/backup.txt"}'

`move_file`¶

Move or rename a file.

Parameters: - source (string, required): Source file path - destination (string, required): Destination file path

Returns: Success confirmation

Example:

mcpp> call filesystem move_file '{"source": "/tmp/old.txt", "destination": "/tmp/new.txt"}'

`delete_file`¶

Delete a file or directory.

Parameters: - path (string, required): Path to delete

Returns: Success confirmation

Example:

mcpp> call filesystem delete_file '{"path": "/tmp/unwanted.txt"}'

`get_file_info`¶

Get detailed metadata about a file or directory.

Parameters: - path (string, required): File or directory path

Returns: Detailed metadata including size, permissions, timestamps

Example:

mcpp> call filesystem get_file_info '{"path": "/tmp/example.txt"}'

Search Operations¶

`search_files`¶

Search for files by name patterns.

Parameters: - path (string, required): Directory to search in - pattern (string, required): File name pattern (supports wildcards)

Returns: Array of matching file paths

Example:

mcpp> call filesystem search_files '{"path": "/tmp", "pattern": "*.txt"}'

`search_within_files`¶

Search for content within files.

Parameters: - path (string, required): Directory to search in - pattern (string, required): Content pattern to search for - file_pattern (string, optional): File name pattern to limit search

Returns: Array of matches with file paths and line numbers

Example:

mcpp> call filesystem search_within_files '{"path": "/tmp", "pattern": "error", "file_pattern": "*.log"}'

Advanced Usage¶

Batch Operations¶

# Read multiple configuration files at once
mcpp> call filesystem read_multiple_files '{
  "paths": ["/etc/nginx/nginx.conf", "/etc/hosts", "/tmp/config.json"]
}'

# Search across multiple file types
mcpp> call filesystem search_within_files '{
  "path": "/var/log",
  "pattern": "ERROR|FATAL",
  "file_pattern": "*.log"
}'

Working with Large Directories¶

# Use tree with depth limit for large directories
mcpp> call filesystem tree '{"path": "/usr", "max_depth": 2}'

# Search specific file patterns to narrow results
mcpp> call filesystem search_files '{"path": "/home", "pattern": "*.py"}'

Security Best Practices¶

# Configure read-only access for sensitive directories
export ALLOWED_DIRS="/etc:/data/config:ro /var/log:/data/logs:ro /tmp:/data/tmp:rw"

# Use specific subdirectories rather than root access
export ALLOWED_DIRS="/home/user/documents /home/user/projects"

Claude Desktop Configuration¶

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/user/documents:/data/docs:ro",
        "-v", "/tmp:/data/tmp:rw",
        "-e", "ALLOWED_DIRS=/data/docs /data/tmp",
        "dataeverything/mcp-filesystem"
      ]
    }
  }
}

Continue.dev Integration¶

{
  "models": [...],
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "mcp-template",
      "args": ["run-tool", "filesystem"],
      "env": {
        "ALLOWED_DIRS": "/home/user/project /tmp"
      }
    }
  ]
}

Custom Docker Integration¶

# Development environment
docker run -i --rm \
  -v "$PWD:/data/project:rw" \
  -v "/tmp:/data/tmp:rw" \
  -e ALLOWED_DIRS="/data/project /data/tmp" \
  -e LOG_LEVEL="DEBUG" \
  dataeverything/mcp-filesystem

# Production environment with read-only configs
docker run -i --rm \
  -v "/etc/app:/data/config:ro" \
  -v "/var/log/app:/data/logs:ro" \
  -v "/tmp/app:/data/temp:rw" \
  -e ALLOWED_DIRS="/data/config /data/logs /data/temp" \
  dataeverything/mcp-filesystem

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Configuration Options¶

Property	Type	Environment Variable	Default	Description
`log_level`	string	`LOG_LEVEL`	`INFO`	Logging level (DEBUG, INFO, WARNING, ERROR)
`allowed_dirs`	string	`ALLOWED_DIRS`	``	Allowed directories to scan, create or read from. Defaults to anything that gets mounted to /data directory in container

Development¶

Local Development Setup¶

# Clone and setup
git clone https://github.com/Data-Everything/MCP-Platform.git
cd MCP-Platform

# Install dependencies
pip install -r requirements.txt

# Configure environment
export ALLOWED_DIRS="/tmp /home/user/test-docs"
export LOG_LEVEL="DEBUG"

# Test locally
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | \
  python -m mcp_platform.template.templates.filesystem

Running Tests¶

# Template-specific tests
pytest mcp_platform/template/templates/filesystem/tests/ -v

# Integration tests
pytest tests/test_volume_mount_command_args.py -v

# CLI parsing tests
pytest tests/test_cli_parsing_focused.py -v

Custom Template Development¶

# Create new template based on filesystem
mcp_platform create my-custom-fs --base filesystem

# Modify template.json for custom configuration
# Extend Dockerfile for additional tools
# Add custom tests in tests/ directory

Troubleshooting¶

Common Issues¶

"Directory not allowed" errors - Check ALLOWED_DIRS configuration - Verify paths are absolute and accessible - Use list_allowed_directories to confirm configuration

Permission denied - Ensure Docker has access to mounted directories - Check file/directory permissions on host system - Verify container user has appropriate access

Tools not discovered - Confirm configuration is properly set - Use debug logging: LOG_LEVEL=DEBUG - Test with tools filesystem --force-server

Debug Commands¶

# Check configuration
mcpp> show_config filesystem

# List available tools
mcpp> tools filesystem

# Enable debug logging
mcpp> config filesystem log_level=DEBUG

# Test basic connectivity
mcpp> call filesystem list_allowed_directories '{}'

Performance Optimization¶

# For large directories, use specific patterns
mcpp> call filesystem search_files '{"path": "/large-dir", "pattern": "specific-*.txt"}'

# Batch operations when possible
mcpp> call filesystem read_multiple_files '{"paths": ["file1", "file2", "file3"]}'

# Use tree with depth limits
mcpp> call filesystem tree '{"path": "/large-dir", "max_depth": 2}'

Support¶

For issues, questions, or contributions: - GitHub Issues: MCP-Platform/issues - Discord Community: Join our Discord - Documentation: Full Documentation

License¶

This template incorporates the mcp-filesystem-server from Mark3 Labs. Please review the original project's license terms for complete usage rights and restrictions.

Testing¶

# Run all tests
pytest tests/

# Run unit tests only
pytest tests/ -m "not integration"

# Run with coverage
pytest tests/ --cov=. --cov-report=html

Docker¶

# Build the image
docker build -t dataeverything/mcp-filesystem .

# Run the container
docker run dataeverything/mcp-filesystem

Troubleshooting¶

Common Issues¶

Server won't start: Check that all required environment variables are set
Tool not found: Verify the MCP client is connected properly
Permission errors: Ensure the server has appropriate file system permissions

Debug Mode¶

Enable debug logging by setting the LOG_LEVEL environment variable to DEBUG.

Contributing¶

Contributions are welcome! Please see the main repository's contributing guidelines.

License¶

This template is part of the MCP Server Templates project.

Support¶

For support, please open an issue in the main repository or contact the maintainers.

Filesystem MCP Server Documentation¶

Overview¶

Quick Start¶

Installation & Deployment¶

Usage & API Reference¶

Usage & API Reference¶

Configuration¶

Required Configuration¶

Optional Configuration¶

Usage & API Reference¶

Usage & API Reference¶

Configuration Examples¶

Directory Operations¶

list_allowed_directories¶

list_directory¶

tree¶

create_directory¶

File Operations¶

read_file¶

read_multiple_files¶

write_file¶

modify_file¶

copy_file¶

move_file¶

delete_file¶

get_file_info¶

Search Operations¶

search_files¶

search_within_files¶

Advanced Usage¶

Batch Operations¶

Working with Large Directories¶

Security Best Practices¶

Claude Desktop Configuration¶

Continue.dev Integration¶

Custom Docker Integration¶

Usage & API Reference¶

Configuration Options¶

Development¶

Local Development Setup¶

Running Tests¶

Custom Template Development¶

Troubleshooting¶

Common Issues¶

Debug Commands¶

Performance Optimization¶

Support¶

License¶

Testing¶

Docker¶

Troubleshooting¶

Common Issues¶

Debug Mode¶

Contributing¶

License¶

Support¶

`list_allowed_directories`¶

`list_directory`¶

`tree`¶

`create_directory`¶

`read_file`¶

`read_multiple_files`¶

`write_file`¶

`modify_file`¶

`copy_file`¶

`move_file`¶

`delete_file`¶

`get_file_info`¶

`search_files`¶

`search_within_files`¶