Home / Docs / MCP Server

MCP Server

Overview #

The thurbox-mcp binary exposes Thurbox configuration over the Model Context Protocol . It shares the same SQLite database as the TUI — changes appear immediately via PRAGMA data_version polling.

Transports #

stdio (default)

bash 
$ thurbox-mcp

Streamable HTTP

bash 
$ thurbox-mcp --transport streamable-http              # HTTP on 127.0.0.1:8080
$ thurbox-mcp --transport streamable-http --port 9090  # Custom port

Available Tools #

Project management

Tool Description
list_projects List all active projects
get_project Get a project by name or UUID
create_project Create a new project with name and repo paths
update_project Update project name and/or repos (partial update)
delete_project Soft-delete a project (preserves for undo)

Role management

Tool Description
list_roles List all roles for a project
set_roles Atomically replace all roles for a project

Atomic replacement: set_roles deletes all existing roles and replaces them in a single transaction. To add a role, include all existing roles plus the new one.

MCP server configuration

Tool Description
list_mcp_servers List MCP servers for a project
set_mcp_servers Set MCP servers for a project

Session management

Tool Description
list_sessions List sessions, optionally filtered by project
get_session Get a session by UUID
delete_session Soft-delete a session (TUI cleans up tmux/worktree)
restart_session Queue a session restart (TUI processes the command)
restore_session Restore a soft-deleted session

Scheduled commands

Tool Description
schedule_command Schedule text to be sent to a session at a future time
list_scheduled_commands List pending scheduled commands, optionally by session
get_scheduled_command Get a scheduled command by ID
cancel_scheduled_command Cancel a pending scheduled command

VM management

Tool Description
list_vms List active VMs, optionally filtered by project
get_vm Get a VM by UUID

Container configuration

Tool Description
list_containerfile_templates List template names + files in each
get_containerfile_template Read a template's Containerfile content
set_containerfile_template Create/update a template
delete_containerfile_template Delete a template (refuses "default")
configure_project_container Set project container defaults
get_project_container_config Read current project container config

VM image management

Tool Description
list_vm_images List downloaded VM images with file sizes
download_vm_image Download a VM image from an HTTPS URL
delete_vm_image Delete a cached VM image

Admin Session #

The TUI includes a built-in Admin session that auto-configures thurbox-mcp as an MCP server. Claude Code discovers the config automatically, enabling conversational management inside the TUI.

How it works

  1. On startup, Thurbox creates an admin directory at ~/.local/share/thurbox/admin/
  2. A .mcp.json is written pointing to the thurbox-mcp binary
  3. An "Admin" project is pinned at index 0 with a yellow ⚙ prefix
  4. A single admin session spawns with all MCP tools pre-allowed

Restrictions

  • Cannot be edited ( Ctrl+E shows an error)
  • Cannot be deleted ( Ctrl+D shows an error)
  • Cannot have additional sessions created
  • The admin session cannot be closed ( Ctrl+C shows an error)

Example usage

In the Admin session, use natural language:

Admin session 
"Set up developer and reviewer roles for the my-app project.
Developer should have acceptEdits mode with git auto-approved.
Reviewer should be plan-only with read access."

CLI Integration #

Configure thurbox-mcp in your Claude Code .mcp.json :

.mcp.json 
{
  "mcpServers": {
    "thurbox": {
      "command": "thurbox-mcp",
      "args": []
    }
  }
}