Pico MCP Server

MCP (Model Context Protocol) server for managing git worktrees and workspaces. Provides tools for creating isolated development environments, tracking changes, and managing collaborative workflows.

Features

• Project Discovery: Auto-scan configured directories for git repositories
• Workspace Management: Create and manage isolated git worktrees for tasks
• Metadata Tracking: YAML-based workspace configuration and history
• Auto-commit: Built-in file monitoring and automatic commit system
• Collaboration: Multi-user workspace support with conversation history

Get Started

Install & Use

Option 1: Install Globally

npm install -g @ben-rogerson/pico-mcp

Option 2: Use with npx (no install)

npx @ben-rogerson/pico-mcp

Configuration

Create environment variables (optional):

# Custom project directories (colon-separated)
# Default: ~/Projects:~/Code:~/Developer:~/dev
PROJECT_DIRECTORIES=~/custom-projects:~/work:~/repos

Connect to Claude Desktop / Cursor

Add to your MCP configuration:

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) Cursor: Settings → MCP Servers → Add Server

Option 1: Use via npx (Recommended)

{
  "mcpServers": {
    "pico-mcp": {
      "command": "npx",
      "args": ["-y", "@ben-rogerson/pico-mcp"]
    }
  }
}

Option 2: After global install

{
  "mcpServers": {
    "pico-mcp": {
      "command": "pico-mcp"
    }
  }
}

Available Tools

Discovery & Navigation

• list projects - Discover git repositories in configured directories
• list workspaces - View all workspaces for a repository
• get workspace info - Get detailed workspace information

Workspace Lifecycle

• create workspace - Create isolated worktree for a task
• initialize workspace metadata - Initialize metadata for existing workspace
• archive workspace - Archive completed workspace
• launch workspace - Open workspace in IDE/terminal

Change Management

• list changes from specific workspace - Show detailed changes in a workspace
• force commit workspace - Manually trigger commit in workspace
• merge remote workspace changes into local - Sync remote changes to local workspace

Integration

• generate mr link - Generate GitLab/GitHub merge request link

Development

Run Tests

npm test

Run Inspector

Debug MCP tools with the inspector:

npm run inspect

Format Code

npm run lint

Architecture

• STDIO Transport: Native stdin/stdout communication for MCP clients
• MCP SDK: Model Context Protocol implementation
• Git Worktrees: Isolated development environments
• YAML Metadata: Distributed workspace configuration

Why STDIO?

STDIO (stdin/stdout) was chosen over HTTP/SSE and WebSocket transports for several key reasons:

Simplicity - Zero infrastructure required. No web servers, proxies, or network configuration. Just a command that spawns a process.

Native MCP Support - Claude Desktop and Cursor natively support STDIO transport out-of-the-box. No additional tooling or adapters needed.

Security - Process-level isolation. No exposed ports, no authentication layers, no CORS concerns. Communication stays within the local machine.

Reliability - Direct process communication eliminates network latency, connection drops, and HTTP overhead. Works offline.

Distribution - Users install via npm and run via npx. No deployment, no hosting, no URL management. Works the same everywhere.

Developer Experience - Single command to install and use. No configuration files, no environment setup, no server management.