ws-mcp

An MCP server that gives LLMs full visibility into your ws-cli workspace tree.

Ask your AI assistant things like:

• "What projects have I abandoned? Summarize where I left off on each one."

• "Which workspaces have uncommitted git changes?"

• "What tasks are open across all my ws/ projects?"*

• "Find everything I was working on related to authentication."

The server traverses your workspace tree, reads metadata, checks git status, parses saved browser tabs, reads beads task databases, and exposes it all through MCP tools — no state of its own.

Prerequisites

• Node.js >= 18

• ws-cli installed and configured (provides the workspace tree that this server reads)

Related MCP server: DevContext

Installation

git clone https://github.com/camggould/ws-mcp.git
cd ws-mcp
npm install

Registering with an MCP Client

Claude Code (per-project)

Add a .mcp.json file to any project directory:

{
  "mcpServers": {
    "ws-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ws-mcp/src/server.js"]
    }
  }
}

Claude Code (global)

claude mcp add --global ws-mcp node /absolute/path/to/ws-mcp/src/server.js

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ws-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ws-mcp/src/server.js"]
    }
  }
}

Any MCP-compatible client

ws-mcp uses stdio transport — pipe stdin/stdout to node src/server.js.

Tools

list_workspaces

List all workspaces with metadata. Filter by status, staleness, or tags.

list_workspaces({})
list_workspaces({ status: "active" })
list_workspaces({ stale_days: 30, tags: "coding,research" })

Returns: Array of { name, status, last_opened, created, tags, path }.

get_workspace

Deep-dive into a single workspace. Returns everything the server knows.

get_workspace({ name: "ws/cli" })

Returns:

• meta — status, tags, created/last opened dates

• git — branch, dirty/clean, ahead/behind remote, modified/untracked/staged file counts

• tabs — saved browser tabs from last session (count + URLs)

• tab_history — session count, first/last session timestamps, unique URL count across all sessions

• beads — task tracker summary: total_issues, by_status counts, open_by_priority counts (or null if no beads database)

• days_since_opened / stale — staleness indicator (stale = 30+ days)

• notes — full workspace.md content

get_workspace_tree

Full parent-child hierarchy as a nested JSON tree. No parameters.

get_workspace_tree({})

Returns: Nested tree with { name, children[], meta?, path? } at each node.

find_stale_workspaces

Identify workspaces you may have forgotten about, sorted by most stale first.

find_stale_workspaces({ days: 7 })

Returns: Array of { name, status, last_opened, days_since, tags }.

search_workspaces

Full-text search across workspace names, tags, workspace.md notes, and saved tab URLs.

search_workspaces({ query: "authentication" })

Returns: Array of { workspace, status, matches[] } where each match includes the field name and matching value/context.

summarize_all

High-level dashboard across all workspaces. No parameters.

summarize_all({})

Returns:

• total_workspaces — count

• by_status — breakdown ({ active: 3, paused: 1, ... })

• recently_active — workspaces opened in the last 7 days

• stale_30_plus_days — workspaces untouched for 30+ days

list_beads

List individual tasks from a workspace's beads issue tracker. Supports filtering and returns tasks sorted by priority then creation date.

list_beads({ workspace: "betterlife" })
list_beads({ workspace: "betterlife", status: "open", priority: 1 })

Returns: { workspace, count, issues[] } where each issue includes id, title, description, status, priority, priority_label, type, assignee, labels[], created_at, updated_at.

get_beads_across_workspaces

Aggregate task counts across multiple workspaces. Scope to a parent prefix or query everything.

get_beads_across_workspaces({})
get_beads_across_workspaces({ parent: "ws" })
get_beads_across_workspaces({ status: "open" })

Returns:

• aggregate — total_open, workspaces_with_beads, by_status counts, open_by_priority counts

• workspaces[] — per-workspace breakdown with by_status, open_by_priority, open_total (sorted by most open issues first)

How It Works

┌──────────────┐     stdio      ┌──────────┐     reads      ┌──────────────────┐
│  MCP Client  │ ◄────────────► │  ws-mcp  │ ──────────────► │  ~/Workspaces/   │
│  (Claude,    │   JSON-RPC     │  server  │                 │  .workspace.yaml │
│   Cursor,    │                │          │                 │  tabs.json       │
│   etc.)      │                │          │                 │  tabs-history.jsonl│
└──────────────┘                └──────────┘                 │  workspace.md    │
                                     │                       │  .beads/beads.db │
│  .git/           │
                                     ▼                       └──────────────────┘
                              ~/.config/ws/
                              config.json

1. Reads ~/.config/ws/config.json to find the workspaces root (defaults to ~/Workspaces)

2. Recursively walks the directory tree, following symlinks, looking for .workspace.yaml marker files

3. Parses workspace metadata (YAML), saved tabs (tabs.json), tab history (tabs-history.jsonl), and notes (workspace.md)

4. Reads beads SQLite databases (.beads/beads.db) in read-only mode for task counts and issue listings

5. Runs git status on workspaces that are git repos (via simple-git)

6. Exposes everything through MCP tools over stdio transport

The server is stateless — it reads directly from the filesystem that ws-cli manages. No database, no cache, no background processes.

Development

# Run with auto-reload on file changes
npm run dev

# Run directly
npm start

Dependencies

Related

• ws-cli — the CLI tool that creates and manages the workspace tree this server reads

License

MIT