workspace-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@workspace-mcp Create a new project called demo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
๐ Workspace MCP ๐ ๏ธ
The ultimate local filesystem bridge for Claude Desktop & Claude Code! โก Stop losing code to token limits โ let Claude design, scaffold, build, and save full-stack software projects directly on your hard drive! ๐๐ป
๐ฏ Overview: Solving Claude's Token Limits ๐
When using Claude to build multi-file projects, developers frequently run into output token limits and context window cutoffs:
โ ๏ธ Truncated File Outputs: Claude hits completion token limits mid-file, cutting off output and forcing you to repeatedly ask it to continue.
๐ Lost Progress: When a conversation gets too long or expires, un-saved code in the chat window disappears unless manually copy-pasted into your editor.
๐ซ No Direct Disk Access: Standard web and desktop chats cannot write files directly to your local computer.
๐ช How Workspace MCP Helps ๐
Workspace MCP connects Claude directly to your local filesystem:
๐พ Incremental Local Disk Saves: Every file and folder is saved immediately as Claude works. If Claude hits an output token limit on a long response, everything written up to that point remains 100% safely stored on disk.
๐ Resuming Work: In a new chat prompt, simply ask Claude to read your project files and pick up right where it left off using
read_file,find_text, orupdate_file.๐ Automatic Work Logs (
CLOUD.md): Maintains an architectural work log tracking what was built, key decisions, and next steps for future chat sessions.
Related MCP server: Axme-code
๐งญ Capabilities Guide: What Workspace MCP Does ๐ ๏ธ
Think of workspace-mcp as providing file and project management hands ๐คฒ to your AI assistant. The AI handles the reasoning (what code to write and how to structure it); workspace-mcp handles applying those changes directly to disk in a clean, organized folder layout.
๐จ The 4 Main Tool Categories
Category | Description |
๐๏ธ Project & Folder Management | Create, rename, or remove project roots and subdirectories. |
๐ File Operations | Create, read, edit, move, rename, and delete individual files safely. |
๐ Search & Discovery | Find text across files ( |
๐ Auto-Documentation | Automatically generate |
๐๏ธ 1. Project & Folder Management
create_project๐๏ธ โ Initializes a project directory with a default scaffold.create_directory๐ โ Creates subfolders (e.g.src/,docs/) and missing parent folders automatically.rename_projectโ๏ธ โ Moves or renames an entire project directory.delete_directory๐๏ธ โ Recursively deletes a folder (requires explicitconfirm=true).delete_project๐ฅ โ Permanently removes an entire project directory (requiresconfirm=true).
๐ก Tip: Always start a new application with create_project to keep files scoped inside a dedicated folder!
๐ 2. File Operations
create_fileโจ โ Creates a new file with content (fails if the file already exists to prevent accidental overwrites).write_file๐ โ Overwrites a file completely or creates it if missing (requiresconfirm=trueif overwriting).update_file๐ง โ Performs targeted string edits (find/replace) on existing files without replacing the entire file.append_fileโ โ Appends text to the end of a file without touching existing content.read_file๐ โ Reads a file's full UTF-8 text content.move_file๐ โ Relocates a file to another directory.rename_file๐ท๏ธ โ Renames a file within its current folder.delete_fileโ โ Deletes a single file (requiresconfirm=true).
๐ก Tip: Use create_file for brand new files, update_file for inline edits, and write_file when replacing an entire file!
๐ 3. Search & Discovery
find_text๐ โ Grep-like search across text files for literal strings (e.g. findingTODOcomments or function usages).search_files๐ฏ โ Glob search for files matching a pattern (e.g.**/*.pyor*.ts).list_directory๐ โ Lists files and subdirectories with sizes and metadata.
๐ก Tip: Use search_files when looking for file types or names, and find_text when searching for specific code text across your project!
๐ 4. Auto-Documentation & Validation
generate_readme๐ โ Creates or updates a structuredREADME.md.generate_project_tree๐ด โ Saves an ASCII visual tree map toPROJECT_TREE.md.project_tree๐๏ธ โ Returns an ASCII visual tree in the tool response without saving to disk.generate_cloud_logโ๏ธ โ WritesCLOUD.mddocumenting what was built and why.validate_workspace๐ฅ โ Checks workspace health, server configuration, and limits.validate_path๐ก๏ธ โ Verifies if a path is safe and valid before performing file operations.
๐ Typical Workflow
1. create_project ๐๏ธ โ Initialize project directory
2. create_directory ๐ โ Scaffold subfolders (src/, docs/)
3. create_file โจ โ Write initial source files
4. update_file ๐ง โ Edit and refine code incrementally
5. find_text/search_files๐ โ Locate references or check for TODOs
6. move_file/rename_file ๐ โ Organize file structure
7. generate_project_tree ๐ด โ Save project tree map
8. generate_readme ๐ โ Document setup and usage
9. generate_cloud_log โ๏ธ โ Save AI work log
10. validate_workspace ๐ฅ โ Verify workspace state๐ Connecting to Claude Desktop ๐ค
Claude Desktop manages MCP servers via its configuration file. Using uv allows Claude Desktop to run workspace-mcp automatically in the background without needing to start a server manually! โก
๐ Step 1: Locate claude_desktop_config.json
OS | Config Path |
Windows ๐ช |
|
macOS ๐ |
|
Linux ๐ง |
|
โ๏ธ Step 2: Add Configuration
Add the following to your claude_desktop_config.json. Update the paths to point to your local installation of workspace-mcp and your desired --workspace-root directory:
Windows ๐ช
{
"mcpServers": {
"workspace-mcp": {
"command": "uv",
"args": [
"--directory",
"C:/Users/YourUsername/mcp/servers/workspace-mcp",
"run",
"workspace-mcp",
"--workspace-root",
"C:/Users/YourUsername/AIProjects"
]
}
}
}macOS ๐ / Linux ๐ง
{
"mcpServers": {
"workspace-mcp": {
"command": "uv",
"args": [
"--directory",
"/home/user/workspace-mcp",
"run",
"workspace-mcp",
"--workspace-root",
"/home/user/AIProjects"
]
}
}
}๐ก Note: Requires uv to be installed on your system PATH.
๐ Step 3: Restart Claude Desktop ๐จ
Fully close Claude Desktop (from system tray or menu bar).
Re-open Claude Desktop.
Click the hammer icon (๐จ) in the chat bar to confirm that the workspace-mcp tools are active! ๐
๐ฎ Usage & Master Prompt ๐
๐ Comprehensive Master Prompt
Copy and paste this prompt into Claude Desktop to test all tool capabilities at once:
Using the workspace MCP, create a new project called [project-name]. Set up the following structure: create a src/ directory, add starter files inside it ([file1], [file2]), and create a top-level README.md and .gitignore.
Once the files exist, append a notes section to the README, then update [file1] with the core logic for [feature].
Search the project for any TODO or FIXME comments using find_text. Find all files matching *.[ext] using search_files.
Rename [file2] to [new-name], then move it into a new docs/ directory.
Generate the project tree, generate a proper README, and generate a CLOUD.md log summarizing what was built.
Finally, validate the workspace configuration, and list the contents of the project root to confirm everything is in place.โก Resuming Work After Token Limits
If Claude hits a completion limit mid-task:
Open a new chat session.
Prompt Claude:
"Check the files in
MyProject/src, reviewCLOUD.mdto see what was built so far, and finish implementing the main module."Claude will use
list_directory,read_file, andupdate_fileto continue development seamlessly! ๐
๐ก๏ธ Security Sandbox Architecture ๐
Workspace MCP strictly isolates all operations to the configured --workspace-root:
Claude Desktop (Client ๐ค)
โ
โผ Stdio Transport โก
Workspace MCP Server ๐ฅ๏ธ
โ
โผ
Service Layer โ๏ธ โโโบ PathValidator (os.path.realpath Sandbox ๐ก๏ธ)
โ
โผ
Sandboxed Workspace Root ๐๐ก๏ธ Path Security: All input paths are resolved using
os.path.realpath/Path.resolve(strict=False)to prevent..path traversal sequences and symlink escapes.๐ซ Reserved Names: Windows reserved filenames (
CON,NUL,AUX,COM1-9) are rejected to preserve cross-platform compatibility.๐ Confirmation Gating: Destructive actions (
delete_file,delete_directory, file overwrites) require explicit confirmation flags (confirm=true/overwrite=true).๐ Audit Logs: Operations are logged to both
operations.jsonl(machine-readable) andoperations.log(human-readable text).
๐งฐ Tool Reference ๐ฆ
Category | Tool | Description |
Project ๐๏ธ |
| Scaffolds directory structure + |
| Removes project folder (requires | |
| Renames or relocates a project directory | |
Directory ๐ |
| Creates subdirectories (including missing parents) |
| Deletes directory recursively (requires | |
| Lists directory files and metadata | |
File ๐ |
| Creates a new file |
| Reads UTF-8 text file content | |
| Overwrites file content (requires | |
| Appends text to end of file | |
| Performs | |
| Relocates or renames a file | |
| Deletes a file (requires | |
Search ๐ |
| Glob search for matching filenames |
| Grep-like search across text files | |
| Generates ASCII project tree string | |
Docs ๐ |
| Creates/updates |
| Creates | |
| Saves | |
Validation ๐ฅ |
| Returns server health and settings |
| Validates relative path safety without modifying disk |
โ๏ธ Configuration Reference ๐ง
Settings can be specified via command-line flags or environment variables (WORKSPACE_MCP_*):
Option | Environment Variable | Default | Description |
|
|
| Base sandboxed directory for all operations |
|
|
| Path to YAML/JSON configuration file |
|
|
| File size write limit |
|
|
| Enforces confirmation on file overwrite/delete |
๐ License โ๏ธ
Distributed under the MIT License.
Available Tools
22 toolsappend_fileA
Append text to the end of an existing file.
Args: path: Path relative to the workspace root. The file must already exist. content: Text to append.
Inputs: path (required), content (required). Returns: object
create_directoryA
Create a directory (and any missing parents) inside the workspace.
Args: path: Path relative to the workspace root, e.g. "MyApp/backend/api". exist_ok: If False, error when the directory already exists.
Inputs: path (required), exist_ok. Returns: object
create_fileA
Create a new file with the given content inside the workspace.
Fails with DUPLICATE_FILE if the file already exists unless overwrite=True is passed.
Args: path: Path relative to the workspace root, e.g. "MyApp/backend/main.py". content: Full text content of the file. overwrite: If True, replace an existing file at this path.
Inputs: path (required), content, overwrite. Returns: object
create_projectA
Create a new project inside the workspace with a conventional folder structure (frontend/backend/database/docker/scripts/tests/ docs/assets/config by default) plus .gitignore, Dockerfile, docker-compose.yml, README.md, CLOUD.md and PROJECT_TREE.md.
Args: name: Project (top-level directory) name. Letters, numbers, spaces, '.', '-', '_' only. structure: Optional custom list of subfolder names, replacing the default 9-folder scaffold. description: One-paragraph description used in README/CLOUD.md. include_docker: Whether to generate Dockerfile + docker-compose.yml.
Inputs: name (required), structure, description, include_docker. Returns: object
delete_directoryA
Delete a directory inside the workspace.
Args: path: Path relative to the workspace root. confirm: Must be explicitly True; this is irreversible. recursive: If True (default), delete all contents too. If False, only succeeds when the directory is empty.
Inputs: path (required), confirm, recursive. Returns: object
delete_fileA
Permanently delete a file inside the workspace.
Args: path: Path relative to the workspace root. confirm: Must be explicitly True; this is irreversible.
Inputs: path (required), confirm. Returns: object
delete_projectA
Permanently delete an entire project directory and everything in it.
Args: name: Project name to delete. confirm: Must be explicitly set to True; this is irreversible.
Inputs: name (required), confirm. Returns: object
find_textA
Search file contents for a literal text string (grep-like).
Args: query: Literal text to search for. root: Directory to search under, relative to the workspace root. extensions: Optional list like [".py", ".ts"] to restrict the search. case_sensitive: Whether the match is case sensitive. max_results: Cap on number of matching lines returned.
Inputs: query (required), root, extensions, max_results, +1 more. Returns: object
generate_cloud_logA
(Re)generate CLOUD.md -- the AI work log explaining exactly what was generated in this project and why: goal, architecture decisions, files created/updated, implementation notes, known limitations, and future work.
Args: project_path: Path to the project directory, relative to the workspace root.
Inputs: project_path (required), goal, future_work, files_created, +5 more. Returns: object
generate_project_treeA
(Re)generate PROJECT_TREE.md, a saved visual ASCII tree of the project.
Args: project_path: Path to the project directory, relative to the workspace root.
Inputs: project_path (required). Returns: object
generate_readmeB
(Re)generate README.md for a project with the standard sections: description, features, folder structure, installation, usage, dependencies, configuration, tech stack, future improvements, license.
Args: project_path: Path to the project directory, relative to the workspace root.
Inputs: project_path (required), usage, features, tech_stack, +6 more. Returns: object
list_directoryA
List the immediate contents of a directory inside the workspace.
Args: path: Path relative to the workspace root (default: workspace root). include_hidden: If True, include dotfiles/dotfolders.
Inputs: path, include_hidden. Returns: object
move_fileA
Move (or move+rename) a file to a new location within the workspace.
Args: source_path: Current path, relative to the workspace root. destination_path: New path, relative to the workspace root. overwrite: If True, replace an existing file at the destination.
Inputs: source_path (required), destination_path (required), overwrite. Returns: object
project_treeA
Render a visual ASCII tree of a directory's contents (not saved to disk).
Args: path: Directory to render, relative to the workspace root.
Inputs: path. Returns: object
read_fileA
Read the full text content of a file inside the workspace.
Args: path: Path relative to the workspace root.
Inputs: path (required). Returns: object
rename_fileA
Rename a file in place (keeping it in the same directory).
Args: path: Current path, relative to the workspace root. new_name: New filename (not a full path) -- e.g. "app.py". overwrite: If True, replace an existing file with that name.
Inputs: path (required), new_name (required), overwrite. Returns: object
rename_projectA
Rename (move) a project directory within the workspace.
Args: old_name: Current project name. new_name: New project name. overwrite: If True, replace an existing project at new_name.
Inputs: new_name (required), old_name (required), overwrite. Returns: object
search_filesA
Find files by glob pattern (e.g. ".py", "**/.test.ts").
Args:
pattern: Glob pattern, evaluated relative to root.
root: Directory to search under, relative to the workspace root.
max_results: Cap on number of matches returned.
Inputs: pattern (required), root, max_results. Returns: object
update_fileA
Update part or all of an existing file.
Use EITHER (find, replace) for a literal text substitution, OR new_content for a full rewrite -- do not pass both.
Args:
path: Path relative to the workspace root. Must already exist.
find: Literal text to search for (mutually exclusive with new_content).
replace: Replacement text for every match of find (default: "").
new_content: Full replacement content for the file.
count: Max number of find occurrences to replace (-1 = all).
Inputs: path (required), find, count, replace, +1 more. Returns: object
validate_pathA
Check whether a given relative path is valid and safe (no traversal, stays within the workspace, no symlink escape) without performing any read/write operation.
Args: path: Path to validate, relative to the workspace root.
Inputs: path (required). Returns: object
validate_workspaceA
Report the current workspace configuration and health: root directory, whether it exists/is writable, size limits, and allowed extensions.
Inputs: no named parameters. Returns: object
write_fileA
Overwrite a file's entire content (creating it if it doesn't exist).
If the file already exists, confirm=True is required (unless the server's require_overwrite_confirmation setting is disabled).
Args: path: Path relative to the workspace root. content: New full text content of the file. confirm: Must be True to overwrite an existing file.
Inputs: path (required), content (required), confirm. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 22 tools
Multiple file-mutation tools overlap significantly: create_file, write_file, and update_file can all write full file content, and move_file supersedes rename_file. delete_project is essentially a specific case of delete_directory with recursive. Though descriptions are detailed, the boundaries are blurry and agents could easily select the wrong tool.
Most tool names follow a consistent verb_noun snake_case pattern (create_file, delete_directory, generate_readme, validate_workspace). The outlier is project_tree, which is a noun phrase, and it conflicts with the similarly named generate_project_tree, creating a minor inconsistency.
With 22 tools, the set feels heavy, and several tools are near-duplicates (rename_file vs move_file, write_file vs update_file), making it padded. A streamlined set of 15-18 tools could cover the same functionality without redundancy.
File CRUD, search, and project management are well covered, but there is no copy operation for files or directories, and no general rename/move for directories other than top-level projects via rename_project. These are notable gaps for a workspace management tool.
Maintenance
Related MCP Connectors
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides Claude Desktop with direct access to your local file system for development tasks, enabling file operations (read, write, edit), directory browsing, command execution, and codebase search within a configured projects directory.6MIT
- AlicenseNot gradedqualityCmaintenancePersistent project memory + architectural decisions + pre-execution safety hooks for Claude Code. Local-only storage, multi-repo workspace, automatic knowledge extraction via background auditor.8 npm14MIT
- FlicenseNot gradedqualityDmaintenanceProvides filesystem access to Claude via the MCP protocol, enabling local file operations through natural language.-
- AlicenseNot gradedqualityDmaintenanceBridges Claude Code terminal sessions with Claude Chat by exposing session logs as tools, enabling seamless context transfer and two-way communication via a cooperative inbox and optional Google Drive sync.87 npm2MIT