@vibescope/mcp-server

MCP server for Vibescope - enables AI agents to track project progress, tasks, blockers, and decisions.

Installation

Option 1: npx (Recommended - No Installation)

Use directly in your MCP config without installing:

{
  "mcpServers": {
    "vibescope": {
      "command": "npx",
      "args": ["-y", "-p", "@vibescope/mcp-server@latest", "vibescope-mcp"],
      "env": {
        "VIBESCOPE_API_KEY": "your-api-key"
      }
    }
  }
}

Option 2: Global Install

npm install -g @vibescope/mcp-server@latest

Then configure:

{
  "mcpServers": {
    "vibescope": {
      "command": "vibescope-mcp",
      "env": {
        "VIBESCOPE_API_KEY": "your-api-key"
      }
    }
  }
}

Quick Start

Interactive Setup (Recommended)

Run the setup wizard to automatically configure Vibescope for your IDE:

npx -p @vibescope/mcp-server vibescope-cli setup

This guides you through:

1. Selecting your IDE (Claude Code, Claude Desktop, Cursor, or Gemini CLI)
2. Getting your API key from the Vibescope dashboard
3. Writing the configuration file

Claude Code (Manual)

claude mcp add vibescope npx @vibescope/mcp-server@latest \
  --env VIBESCOPE_API_KEY=your_key

Gemini CLI (Manual)

Add to your ~/.gemini/settings.json or project-level .gemini/settings.json:

{
  "mcpServers": {
    "vibescope": {
      "command": "npx",
      "args": ["-y", "-p", "@vibescope/mcp-server@latest", "vibescope-mcp"],
      "env": {
        "VIBESCOPE_API_KEY": "$VIBESCOPE_API_KEY"
      },
      "timeout": 30000,
      "trust": true
    }
  }
}

Then set your API key as an environment variable:

export VIBESCOPE_API_KEY=your_key_here

How to Call MCP Tools (Important for AI Agents)

MCP tools are invoked from within your AI conversation, not via command line.

WRONG - CLI does not have a 'call' command:

# This does NOT work
claude mcp call vibescope start_work_session '{"git_url": "..."}'

RIGHT - Call tools within your conversation response:

# Invoke as a tool call, same as Read, Edit, or Bash
mcp__vibescope__start_work_session(git_url: "...", model: "opus")

The CLI commands (claude mcp, gemini mcp) are only for server configuration (add, remove, list), not for calling tools. All tool invocations happen within the AI conversation context.

Getting an API Key

1. Sign up at vibescope.dev
2. Go to Settings
3. Generate an API key

Available Tools

The MCP server provides 140+ tools for AI agents. Here are the key tools by category:

Session

| Tool | Description | |------|-------------| | start_work_session | Initialize session, get persona, role, and next task | | end_work_session | End session and release claimed tasks | | heartbeat | Keep session active (call every 30-60s) | | get_help | Get guidance on workflows | | discover_tools | List tools by category | | get_tool_info | Get detailed tool documentation |

Projects

| Tool | Description | |------|-------------| | create_project | Create a new project | | update_project | Update project details and git workflow | | get_project_context | Get full project context | | get_git_workflow | Get git branching instructions | | query_knowledge_base | Query aggregated project knowledge |

Tasks

| Tool | Description | |------|-------------| | get_tasks | List tasks, optionally filtered by status | | get_next_task | Get highest priority pending task | | add_task | Create a new task | | update_task | Update task status, progress, or details | | complete_task | Mark a task as completed | | add_subtask | Break down tasks into subtasks | | add_task_reference | Add reference URL (docs, PRs) | | batch_update_tasks | Update multiple tasks at once |

Progress & Context

| Tool | Description | |------|-------------| | log_progress | Log a progress update | | add_blocker | Flag a blocker needing human input | | resolve_blocker | Mark a blocker as resolved | | log_decision | Record an architectural decision | | add_idea | Record an improvement idea | | add_finding | Record an audit finding |

Validation & Deployment

| Tool | Description | |------|-------------| | get_tasks_awaiting_validation | Get tasks needing review | | claim_validation | Claim a task for review | | validate_task | Approve or reject work | | request_deployment | Request a deployment | | check_deployment_status | Check deployment state | | complete_deployment | Mark deployment done |

Collaboration

| Tool | Description | |------|-------------| | add_milestone | Track progress on complex tasks | | create_body_of_work | Group tasks into phases | | create_sprint | Create time-bounded sprints | | checkout_file | Prevent file conflicts | | get_pending_requests | Get human requests | | answer_question | Answer user questions |

Additional Categories

• Organizations: Create, manage, and share projects with teams
• Cost Tracking: Monitor spending with alerts and summaries
• Git Issues: Track merge conflicts and push failures
• Role Management: Configure agent roles (developer, validator, deployer)
• Scheduled Deployments: Schedule recurring deployments

Use discover_tools to explore all categories and get_tool_info for detailed documentation

Rate Limits

• 60 requests per minute per API key
• Warning shown when quota drops below 10 requests