Skip to main content
Glama
WOOWTECH

Woow VK MCP Server

by WOOWTECH
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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)

Related MCP server: Vibe MCP Server

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

Category

Count

Tools

A - Execution

10

start_workspace, create_session, run_session_prompt, get_execution, list_sessions, update_session, list_workspaces, update_workspace, delete_workspace, link_workspace_issue

B - Repo

5

list_repos, get_repo, update_setup_script, update_cleanup_script, update_dev_server_script

C - Issue/Kanban

17

list_organizations, list_org_members, list_projects, create_issue, list_issues, get_issue, update_issue, delete_issue, list_issue_priorities, assign_issue, unassign_issue, list_issue_assignees, add_issue_tag, remove_issue_tag, list_issue_tags, list_tags, create_issue_relationship, delete_issue_relationship

D - Context

1

get_context

Dangerous Tools (destructive operations)

Tool

Risk

delete_workspace

Permanently deletes workspace + worktree

delete_issue

Permanently deletes an issue

start_workspace

Creates worktrees on host filesystem

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:

Category

Tools

Status

C - Issue/Kanban

18 tools

18/18 PASS

B - Repo

5 tools

5/5 PASS

A - Execution

10 tools

10/10 PASS

Total

33 tools

33/33 (100%)

Live Instance

Service

URL

MCP Admin GUI

https://woowtechkxs-vibekanban-mcp.woowtech.io

MCP Endpoint

https://woowtechkxs-vibekanban-mcp.woowtech.io/private_{token}/mcp

VK Remote (Web UI)

https://woowtechkxs-vibekanban.woowtech.io

VK Host

https://woowtechkxs-vibekanban-host.woowtech.io

Related

License

MIT License - see LICENSE for details.

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/WOOWTECH/Woow_vk_mcp_server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server