Integrations

Zubo integrates with popular services via pre-built skill packs. Each integration installs one or more skills and can be connected using API keys or OAuth 2.0 authentication. You can connect integrations via chat, the dashboard, or the connect_service tool. For supported providers, OAuth is the recommended approach — it is more secure, easier to manage, and handles token refresh automatically.

Copy-Paste Task Cards

zubo config set auth.enabled true
zubo auth create-key my-app

zubo config set failover '["openai","ollama"]'
zubo config set providers.ollama.model llama3.3

Common Errors

curl -H "Authorization: Bearer YOUR_KEY" http://localhost:3000/api/dashboard/status

zubo model openai/gpt-4o-mini
zubo logs --follow

ollama serve
ollama pull llama3.3

Connecting an Integration

There are three ways to connect a service:

1. Chat: Tell Zubo directly — for example, "Connect GitHub with token ghp_abc123". Zubo will store the secret and install the skill pack automatically.
2. Dashboard: Navigate to Settings → API Keys. Enter the secret name and value, then Zubo detects the associated integration and installs the skills.
3. CLI: Run zubo start, then use the connect_service tool programmatically to provide the credentials.

When you connect a service, Zubo performs the following steps:

1. Stores the API key as a secret in the local database
2. Installs the relevant skill pack for that service
3. Makes all integration tools available immediately (hot-loaded — no restart required)

GitHub

Getting a Token

1. Go to github.com/settings/tokens
2. Click “Generate new token (classic)”
3. Select the repo and read:user scopes
4. Copy the generated token

Skills Installed

• github_repos — List and search repositories, view repository details
• github_issues — List, search, and create issues on any accessible repository
• github_prs — List and search pull requests, view PR details and diffs

Example

"Connect GitHub with token ghp_abc123xyz"

After connecting, try: "List my GitHub repos" or "Show open issues on myorg/myrepo"

Google

Getting a Key

1. Go to console.cloud.google.com
2. Create a new project (or select an existing one)
3. Navigate to APIs & Services → Library and enable the Gmail, Calendar, Sheets, Docs, and Drive APIs
4. Go to APIs & Services → Credentials
5. Create an API key or OAuth 2.0 client credentials

Skills Installed

• gmail — Read and list emails, search by query
• google_calendar — List upcoming events, get event details
• google_sheets — Read from and write to spreadsheets
• google_docs — Read document content
• google_drive — List and search files across your Drive

Notion

Getting a Token

1. Go to notion.so/my-integrations
2. Click “New integration”
3. Give it a name and select the workspace
4. Copy the Internal Integration Token
5. Important: Share the databases and pages you want Zubo to access with the integration inside Notion (click “Share” on the page and add the integration)

Skills Installed

• notion_databases — List and search databases in your workspace
• notion_pages — Read and search pages by title or content
• notion_search — Full-text search across the entire connected workspace

Linear

Getting a Key

1. Open Linear and go to Settings → API → Personal API Keys
2. Click “Create key”
3. Copy the generated key

Skills Installed

• linear_issues — List, search, and create issues across your teams
• linear_projects — List projects and their statuses

Jira

Jira requires three secrets: your API token, the email address associated with your Atlassian account, and your Jira URL (e.g., https://yourcompany.atlassian.net).

Getting a Token

1. Go to id.atlassian.com/manage-profile/security/api-tokens
2. Click “Create API token”
3. Copy the token
4. Store all three secrets:

   "Store my jira_token: atl_abc123..."
   "Store my jira_email: you@company.com"
   "Store my jira_url: https://yourcompany.atlassian.net"

Skills Installed

• jira_issues — List and search issues using JQL, view issue details
• jira_boards — List boards and their configurations

Slack (Integration)

The Slack integration allows Zubo to proactively send messages to Slack channels and read channel history. This is used for the agent to interact with Slack on your behalf.

Note: This is different from the Slack channel (configured in Channel Setup), which lets users send messages to Zubo via Slack. The integration allows the agent to proactively interact with Slack channels — sending messages, reading history, and responding to events.

Skills Installed

• slack_messages — Send messages to channels and users, read channel message history

Twitter / X

Getting a Token

1. Go to developer.twitter.com
2. Create a project and app
3. Navigate to Keys and Tokens
4. Generate a Bearer Token

Skills Installed

• twitter_posts — Compose and post tweets

Note: The twitter_posts tool has confirm permission level — the agent will always describe the tweet and ask for your explicit approval before posting. This cannot be bypassed.

Claude Code

Zubo integrates with Claude Code in three ways:

1. Task delegation: Zubo can delegate coding tasks to Claude Code CLI. The agent spawns a Claude Code session, passes the task, and collects the result.
2. LLM provider: Use Claude Code as the underlying LLM provider for Zubo's agent loop, leveraging Claude's tool-use capabilities.
3. MCP server mode: Run Zubo as an MCP server (zubo mcp-serve) so Claude Code can access Zubo's tools — memory, knowledge graph, integrations, scheduling, and more — as MCP tools.

Setup

1. Install Claude Code CLI: npm i -g @anthropic-ai/claude-code
2. Ensure your ANTHROPIC_API_KEY environment variable is set, or store it as a Zubo secret: "Store my anthropic_api_key: sk-ant-..."

Using as MCP Server

To let Claude Code use Zubo's tools, start Zubo in MCP server mode and add it to your Claude Code configuration:

# Start Zubo as an MCP server
zubo mcp-serve

Then add Zubo to your Claude Code MCP config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "zubo": {
      "command": "zubo",
      "args": ["mcp-serve"]
    }
  }
}

Claude Code will then have access to Zubo's memory search, knowledge graph, integrations, scheduling, and all other tools.

Example

"Use Claude Code to refactor the auth module in ~/projects/myapp"

Zubo delegates the task to Claude Code, which performs the refactoring and returns the result.

MCP Server Mode

Zubo can run as an MCP (Model Context Protocol) server, exposing all of its tools to any MCP-compatible client. This means Claude Code or any other MCP client can use Zubo's memory, knowledge graph, integrations, scheduling, and other tools natively.

Start the MCP server with:

zubo mcp-serve

The server communicates over stdio using JSON-RPC, following the MCP specification. It exposes Zubo's full tool catalog to the connected client. See the CLI reference for flags and options.

Exposed Tools

When running as an MCP server, Zubo exposes all built-in tools and installed skill tools, including:

• memory_search, memory_write — Zubo's persistent semantic memory
• knowledge_graph — entity-relationship queries
• google_calendar, gmail, github_issues, etc. — all connected integration tools
• schedule_job — create scheduled tasks
• web_search, http_request — web access

This lets you use Zubo as a shared intelligence layer — Claude Code can search your memory, check your calendar, create GitHub issues, or query your knowledge graph, all through MCP.

Integration Summary

Managing API Keys

All integration secrets are managed through the same unified secret system.

Dashboard

• Navigate to Settings → API Keys
• Values are displayed as •••••••• by default
• Click “Reveal” to show the actual secret value
• Click “Edit” to update a secret with a new value
• Click “Delete” to remove a secret entirely (this disables the associated integration)

Chat

You can also manage secrets conversationally:

"List my secrets"
"Delete the github_token secret"
"Update my notion_token to ntn_newvalue123"

OAuth Authentication

In addition to raw API keys, Zubo supports OAuth 2.0 for connecting to services securely. OAuth is the standard authorization protocol used by Google, GitHub, Notion, Linear, and Slack. Instead of pasting long-lived API keys, OAuth lets you authenticate through the provider's own login page. Zubo receives short-lived access tokens and refresh tokens, automatically refreshing them when they expire — so your connections stay alive without manual intervention.

Why OAuth?

• More secure — tokens are short-lived and scoped. If compromised, they expire quickly. No permanent API keys sitting in your database.
• Easier to set up — click “Connect” in the dashboard, log into the provider, and approve. No hunting for API key pages.
• Granular permissions — you choose exactly which scopes to grant during the OAuth flow (e.g., read-only calendar vs. full calendar access).
• Automatic refresh — Zubo handles token refresh behind the scenes. When an access token expires, Zubo uses the stored refresh token to get a new one without any user action.
• Revocable — revoke access at any time from the provider's settings or from Zubo's dashboard. No need to rotate API keys.

Supported OAuth Providers

Setting Up OAuth

OAuth requires a one-time setup where you register an OAuth app with each provider. This gives you a clientId and clientSecret pair that Zubo uses to initiate the authorization flow.

Step 1: Create an OAuth App with the Provider

Each provider has its own developer console for creating OAuth apps:

• Google: Google Cloud Console → APIs & Services → Credentials — Create an OAuth 2.0 Client ID. Set the redirect URI to http://localhost:3000/oauth/callback (or your configured dashboard port).
• GitHub: Settings → Developer Settings → OAuth Apps — Register a new app. Set the callback URL to http://localhost:3000/oauth/callback.
• Notion: My Integrations — Create a public integration and set the redirect URI.
• Linear: Settings → API → OAuth Applications — Create a new application with the callback URL.
• Slack: api.slack.com/apps — Create a new app and configure OAuth & Permissions with the redirect URL.

Step 2: Add Credentials to config.json

Add the clientId and clientSecret for each provider you want to use to your ~/.zubo/config.json:

{
  "oauth": {
    "providers": {
      "google": {
        "clientId": "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
        "clientSecret": "YOUR_GOOGLE_CLIENT_SECRET"
      },
      "github": {
        "clientId": "YOUR_GITHUB_CLIENT_ID",
        "clientSecret": "YOUR_GITHUB_CLIENT_SECRET"
      },
      "notion": {
        "clientId": "YOUR_NOTION_CLIENT_ID",
        "clientSecret": "YOUR_NOTION_CLIENT_SECRET"
      },
      "linear": {
        "clientId": "YOUR_LINEAR_CLIENT_ID",
        "clientSecret": "YOUR_LINEAR_CLIENT_SECRET"
      },
      "slack": {
        "clientId": "YOUR_SLACK_CLIENT_ID",
        "clientSecret": "YOUR_SLACK_CLIENT_SECRET"
      }
    }
  }
}

You only need to add the providers you plan to use. Providers without credentials are simply skipped.

Step 3: Connect via Dashboard or Chat

Once credentials are configured, connect in one of two ways:

• Dashboard: Navigate to Settings → OAuth Connections. Click “Connect” next to the provider. You will be redirected to the provider's login page. After approving, you are redirected back and the tokens are stored automatically.
• Chat: Ask Zubo directly — for example, "Connect my Google account" or "Set up GitHub OAuth". Zubo will provide a link to complete the OAuth flow.

Automatic Token Refresh

OAuth access tokens are short-lived (typically 1 hour for Google, longer for others). When Zubo detects an expired token, it automatically uses the stored refresh token to obtain a new access token. This happens transparently — you never see an error or get asked to re-authenticate. If a refresh token is revoked or expires (rare), Zubo will notify you and prompt you to re-connect through the dashboard.

Graceful Fallback

OAuth and API keys work side-by-side. If you have both an OAuth token and an API key for the same provider, Zubo prefers the OAuth token. If no OAuth token is available, Zubo falls back to the API key automatically. This means you can adopt OAuth incrementally — start with API keys and upgrade providers to OAuth one at a time without breaking anything.

Dashboard UI

The OAuth Connections panel in the dashboard (Settings → OAuth Connections) shows:

• All configured providers and their connection status (connected, disconnected, expired)
• The account or email associated with each connection
• When the token was last refreshed
• A “Connect” button for disconnected providers and a “Disconnect” button for active ones

The oauth_manage Tool

Zubo includes a built-in oauth_manage tool that the agent uses to manage OAuth connections programmatically. You can interact with it through natural conversation:

• "List my OAuth connections" — shows all providers and their status (oauth_manage with action list)
• "Connect my GitHub account" — initiates the OAuth flow for GitHub (oauth_manage with action connect)
• "Disconnect Google" — revokes and removes the Google OAuth tokens (oauth_manage with action disconnect)
• "What's the status of my Notion connection?" — checks if the token is valid and when it expires (oauth_manage with action status)

The tool supports four actions: list, connect, disconnect, and status. All token storage and refresh logic is handled internally.

Best Practices

• Use minimum required scopes: When creating API tokens, only grant the permissions each service needs. For GitHub, repo and read:user are sufficient — avoid granting admin or delete scopes.
• Rotate API keys periodically: Update your tokens every few months by editing the secret in the dashboard or telling Zubo to update it.
• Check requirements first: Before connecting an integration, review which secrets it needs (see the summary table above) so you can prepare all required credentials.
• Test after connecting: After storing a secret, verify the integration works by asking Zubo to perform a simple action — for example, "List my GitHub repos" or "Show my upcoming calendar events".
• Secrets are excluded from exports: When you run zubo export, secrets and API keys are automatically excluded to prevent accidental credential leakage.
• Store secrets via Zubo: Always use the agent, dashboard, or secret_set tool to store credentials. Never put them in environment variables, configuration files, or skill source code.
• Share Notion pages explicitly: The Notion integration can only access pages and databases that have been explicitly shared with the integration — it does not have access to your entire workspace by default.
• Prefer OAuth over API keys when available: OAuth tokens are short-lived and automatically refreshed, reducing the risk window compared to long-lived API keys. Use OAuth for Google, GitHub, Notion, Linear, and Slack wherever possible.
• Keep OAuth client secrets out of version control: Your clientId and clientSecret should live only in your local config.json. Never commit them to a repository.
• Request minimal OAuth scopes: When setting up OAuth apps, only request the scopes your agent actually needs. You can always add more later.