MCP Workspace

What mcp-workspace does

The mcp-workspace MCP server gives an AI assistant access to files within a designated project directory through the Model Context Protocol. It supports directory listing, full-file reads, line-range reads, file creation and replacement, appending, exact-text edits, file deletion, directory deletion, and moving or renaming files and directories.

File access is separated into a writable main project and optional read-only reference projects. Reference projects can provide documentation, examples, shared libraries, or other codebases for context without allowing file modifications. The server can also expose GitHub issue, pull request, search, and label operations across configured repositories; issue creation, editing, and commenting are supported as well.

For the confirmed File Systems category, mcp-workspace is relevant when an assistant needs to inspect or change a local codebase while keeping its filesystem scope explicit.

How it works

Start the server with a required --project-dir argument. Every main-project path is checked against that directory before an operation runs. Validation rejects paths containing .., resolves symlinks when possible, and blocks paths that resolve outside the project. Reference projects receive the same path checks against their own directories.

The server uses FastMCP and communicates through MCP. File edits use exact string matching, with an option to replace multiple matches and an option to preserve indentation. Directory removal is non-recursive by default and can be made recursive explicitly. Moving a tracked file uses git mv; otherwise, the server performs a filesystem move.

Reference projects are added with repeatable name=path arguments. They are read-only for file operations, can be discovered by the assistant, and may use relative or absolute paths. Duplicate names are automatically given numeric suffixes. Invalid references are logged as warnings while valid references remain available.

Setup and configuration

Clone the repository, optionally create a virtual environment, and install it with pip from the project directory:

git clone https://github.com/MarcusJellinghaus/mcp-workspace.git
cd mcp_workspace
pip install -e .

Run the installed command with a project path:

mcp-workspace --project-dir /path/to/project

Useful options include repeated --reference-project, --log-level, --log-file, and --file-size-limit. --fail-on-reviews sets the default review gate for branch-status checks. Base-branch formatting enforcement for GitHub issue bodies is enabled by default and can be disabled with --no-enforce-base-branch-format.

Tools and capabilities

The mcp-workspace MCP server includes capabilities for:

• Listing project and reference-project directories.
• Reading complete files or selected line ranges.
• Saving, appending, deleting, moving, and renaming files.
• Removing directories, including recursive deletion when requested.
• Editing exact text with optional multi-match replacement.
• Discovering configured reference projects.
• Reading reference files without modifying them.
• Accessing GitHub issues, pull requests, searches, and labels across repositories.
• Creating, editing, and commenting on GitHub issues.
• Recording human-readable or JSON-structured logs with call parameters, timing, results, and error context.

Limitations and notes

File writes are restricted to the main project directory; reference-project files are read-only. A symlink that points outside an allowed project is rejected when the operating system can resolve it. If path resolution fails, validation falls back to lexical checks, so the outside-target symlink case may not be detected.

The --project-dir value must exist and be a valid directory. Startup errors go to stderr and may also be written to a startup log. Unrecognized command-line arguments are ignored and logged as warnings rather than stopping startup. The README identifies Claude Desktop as an example client, but does not describe client-specific setup beyond running the MCP command.