Woow VK MCP Server

Woow VK MCP Server

WoowTech Three-Piece MCP Service for Vibe Kanban Proxy + Admin GUI + Supergateway Bridge — 33 VK Tools via Authenticated SSE/StreamableHttp

Architecture • Tools • Screenshots • Deployment • Connection • 中文文件

Overview

A production-ready MCP (Model Context Protocol) service that exposes 33 Vibe Kanban tools to external AI agents (Claude, n8n, custom) via authenticated HTTPS endpoints. Follows the WoowTech standard three-piece MCP pattern proven across K3s, Odoo, Hermes, and n8n deployments.

How It Works

Claude App / AI Agent
  → HTTPS (Cloudflare Tunnel)
    → Proxy (token auth + reverse proxy)
      → Supergateway (stdio → StreamableHttp bridge)
        → vibe-kanban-mcp binary (33 tools, Rust)
          → VK Host API (localhost:3000, same Pod)
            → Self-hosted VK Remote (issues/kanban)
            → Self-hosted VK Relay (host connections)

Architecture

Three-Piece Pattern

graph TB
    subgraph "External"
        Agent[AI Agent<br/>Claude / n8n / Custom]
    end

    subgraph "K8s Pod: vk-host"
        subgraph "Container: mcp-service"
            Proxy["件1: Proxy<br/>/private_{token}/*<br/>Token Auth + SSE Forward"]
            Admin["件2: Admin GUI<br/>FastAPI + React SPA<br/>:8080"]
            SG["件3: Supergateway<br/>stdio → StreamableHttp<br/>:8000"]
            MCP["vibe-kanban-mcp<br/>--mode global<br/>33 tools (Rust binary)"]
        end

        subgraph "Container: host"
            Host["VK Host Server<br/>:3000<br/>Workspace + Agent Executor"]
        end
    end

    subgraph "Other Pods"
        Remote["VK Remote<br/>Web UI + API<br/>:8081"]
        Relay["VK Relay<br/>WebSocket<br/>:8082"]
        DB[(PostgreSQL 16)]
        Electric[ElectricSQL]
    end

    Agent -->|HTTPS| Proxy
    Proxy --> SG
    SG -->|stdio| MCP
    MCP -->|localhost:3000| Host
    Host --> Remote
    Host --> Relay
    Remote --> DB
    Electric --> DB

Sidecar Deployment

The MCP service runs as a sidecar container in the same Pod as the VK Host. They share a network namespace, enabling localhost:3000 direct access without authentication (Host has no auth middleware — security boundary is the Pod network).

┌──────────────── K8s Pod: vk-host ────────────────┐
│                                                    │
│  Container: mcp-service        Container: host     │
│  ┌─────────────────────┐      ┌──────────────────┐│
│  │ Proxy    :8080       │      │ VK Host   :3000  ││
│  │ Gateway  :8000       │◄────►│ Claude Code      ││
│  │ vibe-kanban-mcp      │      │ OpenCode         ││
│  └─────────────────────┘      └──────────────────┘│
│       localhost network (shared)                    │
└────────────────────────────────────────────────────┘

Tools

33 MCP Tools in 4 Categories

Dangerous Tools (destructive operations)

Note: This proxy-upstream architecture exposes all tools. Selective blocking requires the future own-server migration. See deny-list.yaml.

Screenshots

Login Page

Dashboard

System health overview showing MCP Server, Proxy, and Tunnel status.

Tools (33 VK MCP Tools)

Complete tool registry organized by category with danger flags.

Token Management

Generate, rotate, and manage MCP authentication tokens.

Log Viewer

Real-time supergateway and proxy logs.

Settings

MCP server configuration and connection settings.

Deployment

Prerequisites

• K3s / Kubernetes cluster with existing VK stack (PostgreSQL, ElectricSQL, Remote, Relay, Host)
• podman or docker for building images
• Cloudflare account (for tunnel)

Build

# Build the MCP service image
podman build -t vk-mcp:v1.0 .

# Import to K3s
podman save localhost/vk-mcp:v1.0 -o /tmp/vk-mcp.tar
# (use privileged Job to import into containerd)

K8s Deployment (Sidecar)

Add the mcp-service container to the existing vk-host Pod:

containers:
  - name: host          # existing
    image: localhost/vk-host:v0.1.43
    ports: [{containerPort: 3000}]
  - name: mcp-service   # NEW sidecar
    image: localhost/vk-mcp:v1.0
    ports:
      - {containerPort: 8080, name: mcp-admin}
      - {containerPort: 8000, name: mcp-sse}
    env:
      - {name: VIBE_BACKEND_URL, value: "http://localhost:3000"}
      - {name: MCP_AUTH_TOKEN, value: "<your-token>"}

Cloudflare Tunnel

Add route: your-mcp-domain.example.com → vk-host-svc:8080

Connection

Claude App / Claude Desktop

https://<your-mcp-domain>/private_<token>/mcp

Claude Code / Settings JSON

{
  "mcpServers": {
    "vibe-kanban": {
      "type": "url",
      "url": "https://<your-mcp-domain>/private_<token>/mcp"
    }
  }
}

Token Management

1. Login to Admin GUI: https://<your-mcp-domain>/ (password: admin)
2. Navigate to Tokens page
3. Click Rotate Token to generate a new token
4. Use the token in your MCP connection URL

Project Structure

woow_vk_mcp_server/
├── mcp_admin_core/          # 件1: Shared MCP proxy + auth (zero-change copy)
│   ├── proxy.py             # SSE/StreamableHttp reverse proxy with token auth
│   ├── process.py           # Subprocess manager for supergateway
│   ├── app.py               # FastAPI factory with SPA fallback
│   ├── auth/                # JWT middleware
│   └── config/              # JSON config store
├── vk_mcp_admin/            # 件2: VK-specific admin backend
│   ├── main.py              # create_app("VK MCP Admin")
│   ├── tool_registry.py     # 33 tools in 4 categories
│   └── routers/             # health, tools, tokens, logs, config
├── frontend/                # 件2: React SPA (Vite + TailwindCSS)
│   └── src/pages/           # Dashboard, Tools, Tokens, Logs, Settings, Login
├── Dockerfile               # Multi-stage: Node 22 + Python 3.12 + binary
├── entrypoint.sh            # Starts supergateway + uvicorn
├── deny-list.yaml           # Warning: all 33 tools exposed
├── .env.example             # Configuration template
└── pyproject.toml            # Python dependencies

Test Results (33/33 = 100%)

All 33 MCP tools verified with full create → update → delete closed-loop testing:

Live Instance

Related

• Woow VK Docker Compose All — Full VK stack deployment (K3s + Podman)
• Vibe Kanban — Upstream project
• MCP Specification — Model Context Protocol

License

MIT License - see LICENSE for details.

_{Built by WOOWTECH | Powered by Vibe Kanban + MCP}