README.md
日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)
Secure file operations and project scaffolding for AI agents.
Part of MCP Tool Shop
At a Glance
MCP File Forge is a Model Context Protocol (MCP) server that gives AI agents sandboxed, policy-controlled access to the local file system. It ships 17 tools across five categories:
| Category | Tools | Description |
|---|---|---|
| Reading | read_file, read_directory, read_multiple |
Read files and directory listings |
| Writing | write_file, create_directory, copy_file, move_file, delete_file |
Create, modify, copy, move, and delete |
| Search | glob_search, grep_search, find_by_content |
Find files by name pattern or content |
| Metadata | file_stat, file_exists, get_disk_usage, compare_files |
Inspect size, timestamps, existence |
| Scaffolding | scaffold_project, list_templates |
Create projects from templates with variable substitution |
Key properties:
- Sandboxed -- operations are restricted to explicitly allowed directories.
- Read-only mode -- flip one env var to disable all write tools.
- Symlink-safe -- symlink following is off by default to prevent sandbox escapes.
- Windows-first -- designed for Windows paths and conventions, works everywhere.
- Template engine --
{{var}}/${var}substitution plus path-level__var__renaming.
Installation
npm install -g @mcptoolshop/file-forge
Or run directly with npx:
npx @mcptoolshop/file-forge
Claude Desktop Configuration
Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"file-forge": {
"command": "npx",
"args": ["-y", "@mcptoolshop/file-forge"],
"env": {
"MCP_FILE_FORGE_ALLOWED_PATHS": "C:/Projects,C:/Users/you/Documents"
}
}
}
}
If you installed globally you can point directly at the binary:
{
"mcpServers": {
"file-forge": {
"command": "mcp-file-forge",
"env": {
"MCP_FILE_FORGE_ALLOWED_PATHS": "C:/Projects"
}
}
}
}
Tool Reference
Reading
| Tool | Description | Key Parameters |
|---|---|---|
read_file |
Read file contents | path, encoding?, start_line?, end_line?, max_size_kb? |
read_directory |
List directory entries | path, recursive?, max_depth?, include_hidden?, pattern? |
read_multiple |
Batch-read multiple files | paths, encoding?, fail_on_error? |
Writing
| Tool | Description | Key Parameters |
|---|---|---|
write_file |
Write or overwrite a file | path, content, encoding?, create_dirs?, overwrite?, backup? |
create_directory |
Create a directory | path, recursive? |
copy_file |
Copy a file or directory | source, destination, overwrite?, recursive? |
move_file |
Move or rename | source, destination, overwrite? |
delete_file |
Delete a file or directory | path, recursive?, force? |
Search
| Tool | Description | Key Parameters |
|---|---|---|
glob_search |
Find files by glob pattern | pattern, base_path?, max_results?, include_dirs? |
grep_search |
Search file contents with regex | pattern, path?, glob?, case_sensitive?, max_results?, context_lines? |
find_by_content |
Literal text search (no regex) | text, path?, file_pattern?, max_results? |
Metadata
| Tool | Description | Key Parameters |
|---|---|---|
file_stat |
File/directory statistics | path |
file_exists |
Check existence and type | path, type? (file / directory / any) |
get_disk_usage |
Directory size breakdown | path, max_depth? |
compare_files |
Compare two paths | path1, path2 |
Scaffolding
| Tool | Description | Key Parameters |
|---|
Tools 6
read_fileRead file contentsread_directoryList directory entrieswrite_fileWrite or overwrite a fileglob_searchFind files by glob patterngrep_searchSearch file contents with regexscaffold_projectCreate projects from templatesEnvironment Variables
MCP_FILE_FORGE_ALLOWED_PATHSComma-separated list of directories the server is allowed to accessMCP_FILE_FORGE_READ_ONLYSet to true to disable all write operationsTry it
→Find all Python files in my project directory that contain the string 'import os'.
→Read the contents of README.md and summarize the project structure.
→Create a new directory named 'logs' and write a status report file inside it.
→Scaffold a new project using the 'web-app' template in the current directory.
→List all files in the src folder recursively, excluding hidden files.