@vibemap.ai/mcp-server

Connect your IDE agent to VibeMap via the Model Context Protocol. Load project specs into any MCP-compatible AI coding agent, or reverse-engineer an existing codebase back into structured VibeMap assets.

Quick Start

{
  "mcpServers": {
    "vibemap": {
      "command": "npx",
      "args": ["-y", "@vibemap.ai/mcp-server"],
      "env": {
        "VIBEMAP_API_KEY": "vm_your_token_here",
        "VIBEMAP_BASE_URL": "https://vibemap.ai"
      }
    }
  }
}

Generate your API key at vibemap.ai → Account → Developer → API Keys.

What It Does

Outbound (VibeMap → IDE): Load your full project context — features, user stories, acceptance criteria, personas, pages, and DB schema — into your IDE agent. The agent builds to spec and updates your VibeMap kanban in real time as it works.

Inbound (IDE → VibeMap): Point the server at an existing codebase and VibeMap's AI will reverse-engineer it into a structured set of features, user stories, and acceptance criteria.

Requirements

• Node.js ≥ 18
• A VibeMap account

IDE Setup

Claude Desktop

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

{
  "mcpServers": {
    "vibemap": {
      "command": "npx",
      "args": ["-y", "@vibemap.ai/mcp-server"],
      "env": {
        "VIBEMAP_API_KEY": "vm_your_token_here",
        "VIBEMAP_BASE_URL": "https://vibemap.ai"
      }
    }
  }
}

Fully restart Claude Desktop after saving. Confirm the 🔨 hammer icon appears in the chat input.

Cursor

Open Settings → MCP and add:

{
  "vibemap": {
    "command": "npx",
    "args": ["-y", "@vibemap.ai/mcp-server"],
    "env": {
      "VIBEMAP_API_KEY": "vm_your_token_here",
      "VIBEMAP_BASE_URL": "https://vibemap.ai"
    }
  }
}

Windsurf

Same format as Cursor. Add to your Windsurf MCP settings file and restart.

Environment Variables

Variable	Description	Default
VIBEMAP_API_KEY	Your Personal Access Token (vm_...)	Required
VIBEMAP_BASE_URL	VibeMap instance URL	http://localhost:3000

Tools

The server exposes 29 tools via the vibemap_ prefix.

Projects & context

Tool	Description
vibemap_list_projects	List all your projects
vibemap_create_project	Create a new project (use before analyze_codebase)
vibemap_get_project_context	Load full project specs into agent context
vibemap_get_atomic_blueprint	Get the code-shaped atomic blueprint for LLM generation
vibemap_list_access_rules	List table- and page-level access rules (with op_conditions) for RLS + auth
vibemap_get_page_source	Retrieve a page and its section source code

Features

Tool	Description
vibemap_list_features	List features with filtering
vibemap_create_feature	Create a new feature
vibemap_update_feature	Update feature fields or status (validates transitions)

User stories

Tool	Description
vibemap_list_user_stories	List stories by project or feature
vibemap_create_user_story	Create a user story
vibemap_update_user_story	Update story fields or status (validates transitions)

Acceptance criteria

Tool	Description
vibemap_list_acceptance_criteria	Fetch BDD criteria
vibemap_create_acceptance_criterion	Create a BDD acceptance criterion
vibemap_update_acceptance_criterion	Update or mark criteria passed/failed (validates transitions)

Kanban — board & agentic lifecycle

Tool	Description
vibemap_get_kanban_board	Get a real-time board view
vibemap_get_next_ready_criterion	Get the highest-priority criterion ready to work on
vibemap_claim_criterion	Claim a criterion (ready → in_progress)
vibemap_report_progress	Append a progress event to a criterion
vibemap_submit_for_review	Submit a criterion for review (→ review_pending)
vibemap_resolve_review	Resolve a review (passed / failed)
vibemap_block_criterion	Block a criterion with a category and reason
vibemap_unblock_criterion	Unblock a criterion with a resolution
vibemap_list_kanban_events	Kanban transition history (for incremental sync)
vibemap_update_kanban_status	⚠️ Deprecated — use the lifecycle tools above

Version control

Tool	Description
vibemap_list_changesets	List changesets (your writes + history) with op counts; includeOps for diffs

Codebase

Tool	Description
vibemap_scan_codebase	Walk a local directory
vibemap_analyze_codebase	Reverse-engineer a codebase into VibeMap assets
vibemap_get_generation_status	Poll AI generation task status

Documentation

Full docs at vibemap.ai/docs/developer-docs/mcp-server/introduction

License

MIT