MCP Setup

ContextSwitch · Model Context Protocol Server

ContextSwitch ships with a bundled MCP server that gives AI agents read/write access to your kanban databases. Add tasks, update status, query across projects, and run AI-assisted retrospectives — all from your coding agent.

Setting up with an AI coding agent?

Copy this page's URL and paste it into your agent. It will fetch the page and follow the machine-readable instructions below.

Then tell your agent: "Set up the ContextSwitch MCP server using the instructions at this URL."

Instructions for AI Coding Agents

You are an AI coding agent. The user wants to install the ContextSwitch MCP server. Follow these steps exactly:

Verify ContextSwitch is installed. Run ls /Applications/ContextSwitch.app. If missing, tell the user to install ContextSwitch from the Mac App Store before continuing.
Confirm the bundled MCP binary exists. Run ls "/Applications/ContextSwitch.app/Contents/MacOS/contextswitch-mcp". Do not proceed until this file exists.
Ask which MCP client the user runs (Claude Desktop, Claude Code, Cursor, Windsurf, Zed). Default to Claude Desktop.
Install the server config using the client-specific steps below. Use this exact server definition under the key contextswitch:
```
{
  "command": "/Applications/ContextSwitch.app/Contents/MacOS/contextswitch-mcp",
  "args": []
}
```
Restart the MCP client.
Verify. Tools include: list-databases, list-items, add-item, update-item, remove-item, add-dependency, remove-dependency, list-dependencies, add-diary-entry, list-diary-entries, update-diary-entry, delete-diary-entry, auto-generate, ai-organize, smart-search. Call list-databases to confirm the server sees the user's open project databases.
If a step fails, read the Troubleshooting section.

What is ContextSwitch MCP?

ContextSwitch stores each project as its own SQLite kanban database. The MCP server gives agents a single endpoint that can list all open databases, add and move tasks between swimlanes, track dependencies, and log diary entries per item — the same operations you do by hand in the app.

Client Instructions

Claude Desktop

Claude Desktop menu bar → Settings → Developer → Edit Config.
Merge into claude_desktop_config.json:

{
  "mcpServers": {
    "contextswitch": {
      "command": "/Applications/ContextSwitch.app/Contents/MacOS/contextswitch-mcp",
      "args": []
    }
  }
}

Save, quit Claude Desktop (⌘Q), reopen.
Confirm contextswitch appears as connected.

Claude Code

claude mcp add contextswitch /Applications/ContextSwitch.app/Contents/MacOS/contextswitch-mcp

Restart and run /mcp to verify.

Cursor

Cursor Settings → MCP → Add new MCP server.
Or edit ~/.cursor/mcp.json directly with the JSON above.

Windsurf / Zed / Other MCP Clients

Any stdio-transport MCP client works. Point it at the binary with empty args.

Available Tools

list-databases

Show every currently open project database.

list-items / add-item

Read kanban swimlanes or create a new task in a lane.

update-item / remove-item

Edit content, move between swimlanes, or delete tasks.

add-dependency / list-dependencies

Model task blockers and retrieve the dependency graph.

add-diary-entry / list-diary-entries

Log per-item progress notes with timestamps.

smart-search

AI-assisted search across items and diary entries.

auto-generate

Generate a starter kanban from a project description.

ai-organize

Reorganize existing items into a cleaner swimlane layout.

Troubleshooting

Tool calls fail with "no database open"

The MCP server operates on whatever database files ContextSwitch currently has open. Open at least one database in the app before calling tools — or pass the database argument with a name returned by list-databases.

Binary not found

Confirm the path with ls /Applications/ContextSwitch.app/Contents/MacOS/. If you installed ContextSwitch outside /Applications, update the command path accordingly.

Gatekeeper warning on first run

Run open /Applications/ContextSwitch.app/Contents/MacOS/contextswitch-mcp once and approve the dialog.

"ai-organize" or "auto-generate" returns an error

These tools require an AI API key configured in ContextSwitch Settings. Open the app → Settings → AI and add a key, then retry.