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)

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.

Parameter	Type	Description
status	string	Filter by status: active, paused, archived, abandoned
stale_days	number	Only show workspaces not opened in this many days
tags	string	Comma-separated tags to filter by (matches any)

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.

Parameter	Type	Description
name	string	Workspace name (e.g. "my-project" or "parent/child")

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.

Parameter	Type	Default	Description
days	number	14	Days without activity to consider stale

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.

Parameter	Type	Description
query	string	Search query (case-insensitive substring match)

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.

Parameter	Type	Default	Description
workspace	string	required	Workspace name (e.g. "betterlife" or "ws/mcp")
status	string		Filter: open, in_progress, blocked, closed
priority	number		Filter: 0=critical, 1=high, 2=normal, 3=low, 4=trivial
type	string		Filter: bug, feature, task, epic, chore
label	string		Filter by label (exact match)
limit	number	50	Max issues to return (1–200)

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.

Parameter	Type	Description
parent	string	Only include workspaces under this prefix (e.g. "ws" for ws/* workspaces). Omit for all.
status	string	Only show workspaces that have at least one issue with this status

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

Package	Purpose
@modelcontextprotocol/sdk	MCP server framework
better-sqlite3	Read-only access to beads task databases
simple-git	Git status checks
js-yaml	Workspace metadata parsing
fast-glob	File pattern matching
zod	Tool parameter validation

Related

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

License

MIT