index.mdβ’12 kB
# 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.
```bash
# Interactive mode (recommended)
mcpt interactive
mcpt> config filesystem allowed_dirs="/tmp /home/user/documents"
mcpt> tools filesystem
mcpt> call filesystem list_directory '{"path": "/tmp"}'
# Direct tool execution
mcpt run-tool filesystem list_directory \
--config allowed_dirs="/tmp /home/user/documents" \
'{"path": "/tmp"}'
```
### 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`
### Configuration Examples
```bash
# 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
mcpt run-tool filesystem list_directory --config-file config.json '{"path": "/tmp"}'
# CLI configuration
mcpt run-tool filesystem list_directory \
--config allowed_dirs="/tmp /home/user/documents" \
--config log_level="DEBUG" \
'{"path": "/tmp"}'
```
## API Reference
### Available Tools
#### Directory Operations
##### `list_allowed_directories`
List all configured allowed directories.
**Parameters**: None
**Returns**: Array of allowed directory paths
**Example**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> 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**:
```bash
mcpt> call filesystem search_within_files '{"path": "/tmp", "pattern": "error", "file_pattern": "*.log"}'
```
## Advanced Usage
### Batch Operations
```bash
# Read multiple configuration files at once
mcpt> call filesystem read_multiple_files '{
"paths": ["/etc/nginx/nginx.conf", "/etc/hosts", "/tmp/config.json"]
}'
# Search across multiple file types
mcpt> call filesystem search_within_files '{
"path": "/var/log",
"pattern": "ERROR|FATAL",
"file_pattern": "*.log"
}'
```
### Working with Large Directories
```bash
# Use tree with depth limit for large directories
mcpt> call filesystem tree '{"path": "/usr", "max_depth": 2}'
# Search specific file patterns to narrow results
mcpt> call filesystem search_files '{"path": "/home", "pattern": "*.py"}'
```
### Security Best Practices
```bash
# 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"
```
## Integration Examples
### Claude Desktop Configuration
```json
{
"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
```json
{
"models": [...],
"mcpServers": [
{
"name": "filesystem",
"command": "mcp-template",
"args": ["run-tool", "filesystem"],
"env": {
"ALLOWED_DIRS": "/home/user/project /tmp"
}
}
]
}
```
### Custom Docker Integration
```bash
# 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
```
## Development
### Local Development Setup
```bash
# Clone and setup
git clone https://github.com/DataEverything/mcp-server-templates.git
cd mcp-server-templates
# 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_template.template.templates.filesystem
```
### Running Tests
```bash
# Template-specific tests
pytest mcp_template/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
```bash
# Create new template based on filesystem
mcpt 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
```bash
# Check configuration
mcpt> show_config filesystem
# List available tools
mcpt> tools filesystem
# Enable debug logging
mcpt> config filesystem log_level=DEBUG
# Test basic connectivity
mcpt> call filesystem list_allowed_directories '{}'
```
### Performance Optimization
```bash
# For large directories, use specific patterns
mcpt> call filesystem search_files '{"path": "/large-dir", "pattern": "specific-*.txt"}'
# Batch operations when possible
mcpt> call filesystem read_multiple_files '{"paths": ["file1", "file2", "file3"]}'
# Use tree with depth limits
mcpt> call filesystem tree '{"path": "/large-dir", "max_depth": 2}'
```
## Support
For issues, questions, or contributions:
- **GitHub Issues**: [mcp-server-templates/issues](https://github.com/DataEverything/mcp-server-templates/issues)
- **Discord Community**: [Join our Discord](https://discord.gg/55Cfxe9gnr)
- **Documentation**: [Full Documentation](https://data-everything.github.io/mcp-server-templates/)
## 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
```bash
# Run all tests
pytest tests/
# Run unit tests only
pytest tests/ -m "not integration"
# Run with coverage
pytest tests/ --cov=. --cov-report=html
```
### Docker
```bash
# Build the image
docker build -t dataeverything/mcp-filesystem .
# Run the container
docker run dataeverything/mcp-filesystem
```
## Troubleshooting
### Common Issues
1. **Server won't start**: Check that all required environment variables are set
2. **Tool not found**: Verify the MCP client is connected properly
3. **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.