Skip to main content
Glama
workspace-mcp

workspace-mcp

๐Ÿš€ 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! ๐Ÿ“๐Ÿ’ป

Python License MCP Protocol


๐ŸŽฏ 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

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 (grep), search by filename patterns (glob), or list directory trees.

๐Ÿ“Š Auto-Documentation

Automatically generate README.md, PROJECT_TREE.md, and CLOUD.md work logs.


๐Ÿ—‚๏ธ 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

OS

Config Path

Windows ๐ŸชŸ

%APPDATA%\Claude\claude_desktop_config.json

macOS ๐ŸŽ

~/Library/Application Support/Claude/claude_desktop_config.json

Linux ๐Ÿง

~/.config/Claude/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 ๐Ÿ“ฆ

Category

Tool

Description

Project ๐Ÿ—๏ธ

create_project

Scaffolds directory structure + .gitignore, Dockerfile, README.md, CLOUD.md

delete_project

Removes project folder (requires confirm=true)

rename_project

Renames or relocates a project directory

Directory ๐Ÿ“

create_directory

Creates subdirectories (including missing parents)

delete_directory

Deletes directory recursively (requires confirm=true)

list_directory

Lists directory files and metadata

File ๐Ÿ“„

create_file

Creates a new file

read_file

Reads UTF-8 text file content

write_file

Overwrites file content (requires confirm=true)

append_file

Appends text to end of file

update_file

Performs find/replace string substitution or partial update

move_file / rename_file

Relocates or renames a file

delete_file

Deletes a file (requires confirm=true)

Search ๐Ÿ”

search_files

Glob search for matching filenames

find_text

Grep-like search across text files

project_tree

Generates ASCII project tree string

Docs ๐Ÿ“˜

generate_readme

Creates/updates README.md

generate_cloud_log

Creates CLOUD.md work log

generate_project_tree

Saves PROJECT_TREE.md to disk

Validation ๐Ÿฅ

validate_workspace

Returns server health and settings

validate_path

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

--workspace-root

WORKSPACE_MCP_WORKSPACE_ROOT

./workspace

Base sandboxed directory for all operations

--config

WORKSPACE_MCP_CONFIG

None

Path to YAML/JSON configuration file

max_file_size_bytes

WORKSPACE_MCP_MAX_FILE_SIZE_BYTES

10485760 (10MB)

File size write limit

require_overwrite_confirmation

WORKSPACE_MCP_REQUIRE_OVERWRITE_CONFIRMATION

true

Enforces confirmation on file overwrite/delete


๐Ÿ“œ License โš–๏ธ

Distributed under the MIT License.

Available Tools

22 tools
append_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

    A3.6/5.0

    Scored across 22 tools

    Disambiguation2/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides 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.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Persistent project memory + architectural decisions + pre-execution safety hooks for Claude Code. Local-only storage, multi-repo workspace, automatic knowledge extraction via background auditor.
      8 npm
      14
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Bridges 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 npm
      2
      MIT