SideButton MCP Server

SideButton

Open-source AI agent platform for agentic coding — MCP server, knowledge packs, and AI workflow automation.

[sidebutton.com](https://sidebutton.com) · [docs.sidebutton.com](https://docs.sidebutton.com)

Run AI coding agents with agentic workflows, knowledge packs, and real browser control. Connect Claude Code, Codex, Cursor, ChatGPT, or any MCP client.

npx sidebutton@latest

Dashboard at http://localhost:9876

What you get

Quick Start

# Install and start

npx sidebutton@latest

Or from source

pnpm install && pnpm build && pnpm start

Open http://localhost:9876

CLI

pnpm cli serve          # Start server with dashboard

pnpm cli serve --stdio # Start with stdio transport (for Claude Desktop) pnpm cli list # List available workflows pnpm cli status # Check server status

Skill pack management

pnpm cli registry add # Install skill packs from a registry pnpm cli registry update [name] # Update installed packs pnpm cli registry remove # Uninstall packs and remove registry pnpm cli search [query] # Search available skill packs

Creating skill packs

pnpm cli init [domain] # Scaffold a new skill pack pnpm cli validate [path] # Validate pack structure pnpm cli publish [source] # Publish to a registry

MCP Server

SideButton is an open-source MCP server for AI coding agents. Agents connect to it directly for browser control, workflow automation, and domain knowledge.

Works with Claude Code, Codex, Cursor, Claude Desktop, VS Code, Windsurf, ChatGPT — any MCP client.

Claude Code

claude mcp add sidebutton --transport http http://localhost:9876/mcp

Persists to ~/.claude.json; add --scope project to write ./.mcp.json instead. Full guide: Claude Code SideButton MCP setup.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.sidebutton]

command = "sidebutton" args = ["serve", "--stdio"]

Full guide: OpenAI Codex SideButton MCP setup.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{

"mcpServers": { "sidebutton": { "command": "npx", "args": ["sidebutton", "--stdio"] } } }

Cursor

Add to ~/.cursor/mcp.json:

{

"mcpServers": { "sidebutton": { "url": "http://localhost:9876/mcp" } } }

MCP Tools

REST API

JSON endpoints for external integrations. The same workflows are available via MCP locally and via REST remotely.

# Run a workflow

curl -X POST http://localhost:9876/api/workflows/check_ticket/run \ -H "Content-Type: application/json" \ -d '{"params": {"ticket_id": "PROJ-123"}}'

List workflows

curl http://localhost:9876/api/workflows

Get run log

curl http://localhost:9876/api/runs/latest

Trigger workflows from webhooks, cron jobs, mobile apps, or other agents on different machines.

Workflow Engine

YAML-first orchestration for agentic workflows. Step types by family:

Step Types

LLM steps work with Ollama (local), OpenAI, and Anthropic.

Example

id: check_ticket_status

title: "Check Jira ticket and classify" steps:

• type: browser.navigate url: "https://your-org.atlassian.net/browse/{{ticket_id}}"
• type: browser.extract selector: "[data-testid='status-field']" as: current_status
• type: control.if condition: "{{current_status}} != 'Done'" then:
• type: llm.classify prompt: "Should this ticket be closed? Context: {{current_status}}" classes: [close, keep_open] as: decision

Variable Interpolation

Use {{variable}} syntax to reference extracted values or parameters:

steps:

• type: browser.extract selector: ".username" as: user
• type: shell.run cmd: "echo 'Hello, {{user}}!'"

Knowledge Packs

Installable domain knowledge (skill packs) per web app or domain. Knowledge packs power AI code review, automated testing, and enterprise AI agent deployments.

Also referred to as skill packs in code and CLI commands.

• Selectors — CSS selectors for UI elements
• Data models — entity types, fields, relationships, valid states
• State machines — valid transitions per state
• Role playbooks — role-specific procedures (QA, SE, PM, SD)
• Common tasks — step-by-step procedures, gotchas, edge cases

sidebutton install github.com

sidebutton install atlassian.net

Open registry with published packs for popular web apps. Build and share packs for any domain.

Chrome Extension

Install the [SideButton Chrome Extension](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij) from the Chrome Web Store.

• Browser commands — navigate, click, type, extract, scroll, wait, snapshot
• Real DOM access via CSS selectors — not pixel coordinates, not screenshots
• Recording mode — capture manual actions as workflows
• Embed buttons — inject action buttons into any web page
• WebSocket connection — stable reconnection, works with local or remote server

After installing:

1. Navigate to any website
2. Click the SideButton extension icon
3. Click "Connect This Tab"

Dashboard & Observability

Svelte UI at http://localhost:9876:

• Workflow browser — list, search, run
• Run logs — step-by-step execution traces with timing, variables, errors
• Skill pack manager — install, browse, inspect
• System status — extension connection, LLM config, server health

SideButton handles multi-agent orchestration — from workflow execution to knowledge injection.

Architecture

┌──────────────────────────────────────────────────────────────────────────┐

│ @sidebutton/server │ │ │ │ ┌─────────────────────┐ ┌──────────────────────────────────────────┐ │ │ │ stdio Transport │ │ Fastify HTTP + WebSocket (port 9876) │ │ │ │ ───────────────── │ │ ──────────────────────────────────── │ │ │ │ stdin → JSON-RPC │ │ GET / → Dashboard (Svelte) │ │ │ │ stdout ← JSON-RPC │ │ GET /ws → Chrome Extension WS │ │ │ │ (Claude Desktop) │ │ POST /mcp → MCP JSON-RPC (SSE) │ │ │ └──────────┬──────────┘ │ GET /api/* → REST API │ │ │ │ └──────────────────────┬───────────────────┘ │ │ │ │ │ │ └──────────────────┬──────────────────┘ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────────────┐ │ │ │ @sidebutton/core │ │ │ │ │ │ │ │ - Workflow types & parser (YAML) │ │ │ │ - Step executors (YAML step types) │ │ │ │ - Variable interpolation │ │ │ │ - Execution context & events │ │ │ └────────────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────────┘ ▲ ▲ ▲ ▲ │ stdio │ WebSocket │ HTTP POST │ REST ▼ ▼ ▼ ▼ ┌──────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌───────────────────┐ │Claude Desktop│ │ Chrome Extension│ │ Claude Code │ │ Mobile App │ │ (MCP stdio) │ │ (Browser Auto) │ │ (MCP SSE) │ │ (REST Client) │ └──────────────┘ └─────────────────┘ └─────────────────┘ └───────────────────┘

Project Structure

sidebutton/

├── packages/ │ ├── core/ # @sidebutton/core — workflow engine │ │ └── src/ │ │ ├── types.ts # Workflow types │ │ ├── parser.ts # YAML loader │ │ ├── executor.ts # Workflow runner │ │ └── steps/ # Step implementations │ ├── server/ # @sidebutton/server — MCP + HTTP + CLI │ │ ├── bin/ # CLI entry poi