workspace-mcp

An MCP server that exposes workspace file operations — read, write, edit, search, and manage files across sandboxed workspaces.

Features

• Workspace management — create, list, and switch between isolated workspaces
• File operations — read, write, edit, copy, move, remove files
• Search — grep (regex content search) and glob (file pattern matching)
• Directory operations — list, create, tree view
• Structured logging — JSON logs with configurable levels and file/stderr output via pino
• Transports — stdio (default) and HTTP
• Cross-platform binaries — pre-compiled for macOS, Linux, and Windows

Usage

Run directly with npx — no installation required:

npx @mattsanchez/workspace-mcp

Or with environment variables:

DEFAULT_WORKSPACE_NAME=my-project DEFAULT_WORKSPACE_DIR=/path/to/project npx @mattsanchez/workspace-mcp

To use with the MCP Inspector:

npx @modelcontextprotocol/inspector npx @mattsanchez/workspace-mcp

HTTP mode:

TRANSPORT=http PORT=3100 npx @mattsanchez/workspace-mcp

Development

# Install dependencies
bun install

# Run in stdio mode (default)
bun run dev

# Run in HTTP mode
TRANSPORT=http PORT=3100 bun run dev

# Run tests
bun test

# Type check
bun run typecheck

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | CONFIG_DIR | ~/.otto | Directory for workspace configuration | | TRANSPORT | stdio | Transport type: stdio or http | | PORT | 3100 | HTTP server port (when TRANSPORT=http) | | DEFAULT_WORKSPACE_NAME | — | Pre-configure a default workspace name | | DEFAULT_WORKSPACE_DIR | — | Pre-configure a default workspace directory | | LOG_LEVEL | info | Log verbosity: debug, info, warn, or error | | LOG_FILE | — | Path to log file; when unset, logs go to stderr |

Logging

workspace-mcp uses pino for structured JSON logging. Logs are written to stderr by default (safe for stdio transport) or to a file when LOG_FILE is set.

# Debug logging to a file
LOG_LEVEL=debug LOG_FILE=/tmp/mcp.log npx @mattsanchez/workspace-mcp

# Errors only
LOG_LEVEL=error npx @mattsanchez/workspace-mcp

What gets logged at each level:

| Level | Events | |-------|--------| | error | Error details with stack traces | | warn | Stale workspace pruning | | info | Server startup, workspace create/delete | | debug | Tool calls with arguments, HTTP requests, resource access |

Building

Standalone binaries for all platforms:

bun run build          # all platforms
bun run build:macos    # macOS arm64 + x64
bun run build:linux    # Linux arm64 + x64
bun run build:windows  # Windows x64

Client usage

The package also exports a client for connecting to the MCP server programmatically:

import { RemoteWorkspaceFS, McpToolCaller } from "@mattsanchez/workspace-mcp/client";

License

Apache 2.0