# workspaceguard [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/RudrenduPaul/WorkspaceGuard  
**GitHub Stars:** 0  
**npm Downloads (last month):** 230  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/workspaceguard

## Description
Wraps the WorkspaceGuard CLI as a single generic MCP tool for workspace usage checks.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "workspaceguard": {
    "command": "npx",
    "args": ["-y","workspaceguard-cli"],
    "env": {
      "WORKSPACEGUARD_DATA_DIR": ""
    }
  }
}
```

**Requires environment variables:** `WORKSPACEGUARD_DATA_DIR` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What workspaceguard MCP server does

The workspaceguard MCP server connects an MCP-compatible agent to the WorkspaceGuard CLI used alongside Odysseus or a compatible self-hosted AI assistant backend. WorkspaceGuard registers workspaces, associates each one with an identity value, counts messages by workspace and month, and optionally enforces a monthly message cap.

The MCP distribution is included with the Python package as an optional extra. Rather than defining a separate tool for each administrative action, it exposes one generic `run` tool. An agent supplies the same argument list used with the `workspaceguard` command, such as `usage --json` or `status --json`.

## How it works

The MCP tool starts the installed CLI as a subprocess, reads its JSON output, and returns the parsed result. Failures are converted into an error dictionary instead of being raised by the MCP server. This covers cases such as a missing executable, launch failure, timeout, non-zero exit status, or output that cannot be parsed.

WorkspaceGuard's request path resolves the workspace, checks its quota, calls the backend, and records usage. A workspace at its cap receives a quota error before the backend is called. If the usage store cannot be read, the guard blocks the request rather than resetting the count. Backend failures can open a circuit after three consecutive failures; a later half-open probe can close it after a successful call.

## Setup and configuration

Install the Python package with its MCP extra:

```bash
pip install "workspaceguard-cli[mcp]"
```

The CLI itself can also be installed from npm with `npm install -g workspaceguard-cli`, or run through `npx workspaceguard-cli`. The installed command is `workspaceguard`.

Initialize the data directory, register workspaces, and optionally set caps with the CLI. For example, `workspaceguard add-workspace alex --identity alex@example.com` registers an identity, while `workspaceguard set-cap alex 1000` applies a monthly limit. The MCP server then invokes these commands through `run`.

Data is stored under `--data-dir` when supplied, otherwise under the `WORKSPACEGUARD_DATA_DIR` environment variable, and finally under `~/.workspaceguard`. The `--force` option is limited to initialization and permanently invalidates data encrypted with an unrecoverable old key.

## Tools and capabilities

The workspaceguard MCP server provides the generic `run` tool. Through it, an agent can invoke:

- `init` to initialize configuration and the vault
- `add-workspace` to register a workspace and identity
- `status --json` to list configured workspaces
- `usage --json` to retrieve counts, caps, percentages, period, and estimated bytes
- `set-cap` to set or clear a monthly message limit
- `rotate-key` to re-encrypt a workspace's secrets under a new key
- `scan --json` to run the current isolation scan stub

Every command accepts `--json`; structured output is intended for agents and orchestrators rather than terminal scraping.

## Limitations and notes

The MCP layer is a subprocess wrapper, not a separate quota engine. The `workspaceguard` executable must be installed and available to it. The `scan` command is currently a scaffold and always returns an empty finding list, so it should not be treated as an active isolation audit.

The README names Claude Desktop and Claude Code as MCP-compatible clients. WorkspaceGuard's underlying backend is described as Odysseus or a compatible self-hosted assistant deployment; compatibility with other backends is not specified beyond that description.

_Full upstream README: https://allmcps.com/mcp/workspaceguard/readme_