🚀 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:

1. ⚠️ Truncated File Outputs: Claude hits completion token limits mid-file, cutting off output and forcing you to repeatedly ask it to continue.

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

3. 🚫 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, or update_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

🗂️ 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 explicit confirm=true).

• delete_project 💥 — Permanently removes an entire project directory (requires confirm=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 (requires confirm=true if 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 (requires confirm=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. finding TODO comments or function usages).

• search_files 🎯 — Glob search for files matching a pattern (e.g. **/*.py or *.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 structured README.md.

• generate_project_tree 🌴 — Saves an ASCII visual tree map to PROJECT_TREE.md.

• project_tree 👁️ — Returns an ASCII visual tree in the tool response without saving to disk.

• generate_cloud_log ☁️ — Writes CLOUD.md documenting 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

⚙️ 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 🔨

1. Fully close Claude Desktop (from system tray or menu bar).

2. Re-open Claude Desktop.

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

1. Open a new chat session.

2. Prompt Claude:

   "Check the files in MyProject/src, review CLOUD.md to see what was built so far, and finish implementing the main module."

3. Claude will use list_directory, read_file, and update_file to 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) and operations.log (human-readable text).

🧰 Tool Reference 📦

⚙️ Configuration Reference 🔧

Settings can be specified via command-line flags or environment variables (WORKSPACE_MCP_*):

📜 License ⚖️

Distributed under the MIT License.