Skip to main content

Claude Code Plugin

The Campbooks plugin for Claude Code connects your coding agent to your inbox over MCP. Once installed, two skills handle the heavy lifting: /campbooks:setup walks you through onboarding, and /campbooks:triage runs your daily inbox session.

Install​

In a Claude Code session:

/plugin marketplace add notacamp/campbooks
/plugin install campbooks@campbooks

Claude Code will prompt for two things:

  1. Campbooks server URL — https://app.campbooks.not-a-camp.com for Campbooks Cloud, or your own instance URL (no trailing slash).
  2. MCP key — a non-expiring credential; see below.

Creating the MCP key​

Short-lived OAuth tokens expire after two hours and cannot be used in a static agent config. An MCP key stays valid until you rotate or delete it.

  1. In your Campbooks instance open Settings → API access and click New client.
  2. Give it a name — "Claude Code agent" works fine.
  3. Select the scopes it needs (see below), then click Create.
  4. On the next page you will see the MCP key: a single string in the form <client-id>.<client-secret>. Copy it now — it is shown only once. If you lose it, regenerate the client secret from the same Settings page.
  5. Paste the key into the mcp_key field in the plugin configuration.

To rotate the key later: go to Settings → API access, find the client, and regenerate its secret. The old key stops working immediately.

Scope sets​

Scopes are a ceiling on what the agent can do. Narrower scope = fewer tools in tools/list = less context used per session. Pick what you actually need.

Full set (recommended for power users):

emails:read emails:write emails:send
tags:read tags:write
documents:read documents:write
document_types:read document_types:write
contacts:read contacts:write
calendar:read calendar:write
reminders:read reminders:write
tasks:read tasks:write
folders:read folders:write
email_accounts:read email_accounts:write
scout:read scout:write
scheduled_emails:read scheduled_emails:write

Triage-only (read + skim, no send):

emails:read emails:write
tags:read documents:read calendar:read tasks:read reminders:read

Read-only (query only, no changes):

emails:read documents:read calendar:read tasks:read

The three context tools — get_overview, get_setup_status, and guide — require no scope and are always available to any authenticated client.

Skills​

The plugin ships two skills you can invoke directly in a Claude Code session.

/campbooks:setup — guided onboarding​

Run this the first time, or any time the plugin is not connecting. It walks you through the following in order, one question at a time:

  1. Verify the MCP connection — calls get_setup_status. If the call fails, it walks you through creating the API client and pasting the MCP key.
  2. Connect a mailbox — if no email account is connected yet, it asks whether you are on Campbooks Cloud or running your own instance:
    • Cloud path: calls connect_email_account(mode: "web") and gives you the OAuth URL to open in a browser. Wait for the OAuth flow to complete, then confirm.
    • Self-hosted path: offers the local OAuth helper script (see Local OAuth below).
  3. AI parsing — reports your current AI setup and offers to enable managed AI or guide you to Settings → AI for a custom key.
  4. Taxonomy — if you have no document types, tags, or folders yet, asks what kind of work the inbox handles and proposes a starter set (for your approval before anything is created).
  5. First skim session — loads the skim deck, shows you the top clusters, and walks through the first decisions.

The skill never creates anything without an explicit "yes" from you.

/campbooks:triage — daily inbox run​

Run this whenever you want to work through what's waiting. It moves through these steps in order (any step can be skipped):

  1. Overview — calls get_overview and reports unread count, awaiting-reply threads, pending documents, today's calendar events, overdue reminders, and suggested tasks. A short paragraph or quick bullet list — just enough to orient you.
  2. Skim deck — loads clusters grouped by ring (priority, notifications, newsletters, etc.), proposes actions, and applies them batch or one by one after your confirmation.
  3. Awaiting reply — lists threads where you sent the last message and haven't heard back. Drafts replies inline; sends only after an explicit "yes, send it".
  4. Pending documents — lists documents awaiting review. Approve, reject, or reclassify, one at a time or in batch.
  5. Suggested tasks and reminders — shows AI-extracted to-dos and reminders; confirms or dismisses each after you see the title.
  6. Closing summary — emails actioned, replies sent, documents approved, tasks confirmed.

What a session looks like​

Here is a typical morning run:

> /campbooks:triage

You have 14 unread emails, 2 threads awaiting a reply from you, 3 documents
pending review (including an invoice from ACME for €1,290), and one overdue
reminder: "Submit VAT return" was due yesterday.

Skim deck — 4 clusters:
  Priority ring
    • ACME invoices — 2 emails — scout suggests keep
  Notifications ring
    • GitHub PR alerts — 9 emails — suggest archive
    • Stripe payment receipts — 4 emails — suggest archive
  Newsletters ring
    • Product digests — 6 emails — suggest archive

Apply these actions (except the ACME keep)?

> yes

Archived 19 emails across 3 clusters. 2 emails kept.

Awaiting reply — 2 threads:
  1. Jane at ACME — "Re: Q3 proposal" — 4 days ago
  2. Bank onboarding — "Your documents" — 2 days ago

Draft a follow-up for the ACME thread?

> yes

"Hi Jane, just following up on the Q3 proposal — happy to hop on a call this
week if that helps. Let me know."

Send this reply?

> yes

Sent. Moving on to documents...

The agent shows you what it is about to do before every write, and waits for your answer.

Local OAuth (self-hosted only)​

If your self-hosted server's OAuth callbacks are not accessible from the public internet, you can mint a refresh token locally and pass it to the server via the MCP API.

Cloud users: use the connect_email_account(mode: "web") flow instead — the /campbooks:setup skill handles this for you automatically.

Prerequisites​

  • Python 3 (standard library only — no pip install needed).
  • The server's own OAuth client credentials — GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET or ZOHO_CLIENT_ID/ZOHO_CLIENT_SECRET from the server's environment. A token minted with a different client_id will fail when the server tries to refresh it.
  • http://localhost:8765/callback added to the OAuth app's allowed redirect URIs (Google Cloud Console → Credentials → your OAuth client → Authorized redirect URIs; Zoho Developer Console → API Console → your client → Redirect URIs).

Run​

python3 integrations/claude-plugin/scripts/campbooks_oauth.py google \
  --client-id YOUR_GOOGLE_CLIENT_ID \
  --client-secret YOUR_GOOGLE_CLIENT_SECRET

# Zoho — specify your server's data-centre region
python3 integrations/claude-plugin/scripts/campbooks_oauth.py zoho \
  --client-id YOUR_ZOHO_CLIENT_ID \
  --client-secret YOUR_ZOHO_CLIENT_SECRET \
  --region eu

Omit --client-id / --client-secret and the script will prompt for them securely. It opens your browser, completes the consent flow, and prints one line of JSON:

{"provider": "google", "refresh_token": "1//0e..."}

The /campbooks:setup skill calls connect_email_account(mode: "token", ...) with that token automatically — you do not need to paste the token into chat. Keep it secure: it grants full mailbox access.

Last updated on