Orbit Desktop MCP

Connect an AI client with MCP

Connect an AI client to Orbit and work with your projects from a conversation.

MCP (Model Context Protocol) lets an AI client work with another app's tools. Connect a compatible client to Orbit to find project context, create tasks, or update documents from a conversation. This connection is separate from scratchpad AI.

To browse projects inside Codex and start chats with selected tasks, documents, or notes, install the Orbit Browser beta. That plugin provides read-only access through the Orbit Beta Git-backed marketplace.

Copy the local configuration

1. Open Settings → Connections → Connect an AI client in Orbit.
2. Select Copy configuration.
3. Add the copied Orbit server entry to your client's MCP settings, following that client's configuration format. Keep any existing server entries.
4. Reload or restart that client's server connection and approve the Orbit server if prompted.

Use the configuration generated by your installed Orbit app, rather than one copied from another machine. Keep Orbit running for project checks and activity updates.

Claude Code example

For Claude Code, add the copied Orbit entry under mcpServers in .mcp.json at the root of the code project where you use Claude Code. Create the file with Orbit's copied configuration if it does not exist. Restart Claude Code and approve the server when prompted. From that project directory, check the server configuration with:

claude mcp get orbit

Then ask: “List my Orbit projects.” This checks that the client can read your workspace before you request an edit. If it fails, copy a fresh configuration from Orbit and reconnect the server. See Claude Code's MCP documentation for client-specific setup help.

The .mcp.json location determines where Claude Code loads the connection. It does not limit Orbit's tools to a single Orbit project.

What you can ask

Ask your AI client in plain language to:

• Find projects and read their notes, tasks, documents, and files.
• Create or update projects, cards, documents, and attachments.
• Add secrets without revealing saved secret values.
• Check project dependencies, security, and repository activity.
• Update supported preferences, project statuses, and existing Git connections.

Review changes

Ask the client to read a project before editing it. If the project changes while the client is working, it should read the latest version before trying again.

When updating project tags, repositories, folders, or links, ask the client to keep existing items unless you intend to replace or remove them.

For example: “Read my Website project, then add a task named Review launch copy to its To Do list. Preserve existing cards.”

Access boundaries

An AI client can add secrets but cannot reveal saved secret values, PINs, or connection credentials. Unlocking the vault, setting up credentials, system actions, and workspace export/import require the desktop app.

Your AI client may send the information it reads to its own model provider according to that client's settings. Grant access only to clients you want to use with your workspace.