Connect Penlo to Claude

1 What is Penlo MCP?

Penlo MCP is a small connector that lets any AI assistant — Claude, ChatGPT, Cursor, VS Code, and others — search and read your handwritten notes during a conversation. No copy-paste, no file uploads, no export step. Ask the assistant a question about something you wrote in a notebook, and it queries Penlo directly to find the answer.

Under the hood it speaks the Model Context Protocol (MCP), an open standard from Anthropic. Penlo runs an MCP server that exposes three tools:

• search_notes — full-text search across the OCR content of every notebook you've synced.
• find_notebook — locate a notebook by its title or PDF filename.
• list_recent_notes — list your most recently synced notebooks.

2 Prerequisites

Before you start, make sure you have:

• A Penlo account on the Power plan. MCP access is a Power-tier feature. Upgrade in Penlo Settings → Subscription.
• At least one notebook synced and OCR'd. Penlo's MCP server only returns notebooks whose handwriting has been processed. If you've just signed up, give the first sync a few minutes to complete.
• An MCP-compatible AI client. Claude Desktop is the easiest. ChatGPT, Cursor, VS Code, Claude Code, Windsurf, Zed, and others work too.

3 Generate your API key

Every client you install needs the same API key. Generate one first, then reuse it.

1. In Penlo, open Settings → API.
2. Click Generate API Key.
3. Copy the key immediately and store it somewhere safe — a password manager is ideal. The full key is shown only once and cannot be retrieved later. Only the prefix is kept visible in your settings for identification.

4 Install in Claude Desktop

Claude Desktop supports a one-click installer format called .mcpb (MCP Bundle). It's the cleanest install path — no JSON editing, no terminal commands.

Install the bundle

Two paths are available. Use whichever is convenient.

Path A — Double-click

1. Find penlo-mcp.mcpb in your Downloads folder.
2. Double-click the file. Claude Desktop opens automatically and shows an install dialog for Penlo.
3. Click Install.

Path B — Install from inside Claude Desktop

Useful if double-clicking is blocked by macOS Gatekeeper or you prefer to install from within the app.

1. Open Claude Desktop and go to Settings → Extensions.
2. Click Advanced settings and find the Extension Developer section.
3. Click Install Extension… and select the penlo-mcp.mcpb file you downloaded.

Enter your API key

After installing, Claude Desktop prompts you for a Penlo API Key. Paste the key from Section 3 and click Save. Claude stores the key securely in your operating system's keychain — it's never written to disk in plain text.

5 Your first conversation

Start a new chat in Claude and try one of these prompts:

• "Search my Penlo notes for [a topic you've written about]."
• "What did I write about most recently?"
• "Find my notebook called [some title] and summarize it."

Claude will expand a tool-call panel showing which Penlo tool it's using and the result it received, then weave that into its response. If you see real content from your notebooks come back, you're set.

For a longer list of useful prompts — including reasoning across multiple notebooks, drafting from your notes, and finding gaps in your own thinking — see the blog post on getting more out of Penlo MCP.

6 Install in ChatGPT

ChatGPT supports custom MCP servers via Developer Mode in Connectors. Available on Plus, Pro, Business, Enterprise, and Education plans on the web.

7 Install in Cursor

{
  "mcpServers": {
    "penlo": {
      "command": "npx",
      "args": ["-y", "@penloapp/mcp-server"],
      "env": {
        "PENLO_API_URL": "https://notes.penlo.app/mcp",
        "PENLO_API_KEY": "your_penlo_api_key_here"
      }
    }
  }
}

8 Install in VS Code

{
  "servers": {
    "penlo": {
      "command": "npx",
      "args": ["-y", "@penloapp/mcp-server"],
      "env": {
        "PENLO_API_URL": "https://notes.penlo.app/mcp",
        "PENLO_API_KEY": "your_penlo_api_key_here"
      }
    }
  }
}

9 Install in Claude Code

claude mcp add penlo \
  --command npx \
  --args "-y @penloapp/mcp-server" \
  --env PENLO_API_URL=https://notes.penlo.app/mcp \
  --env PENLO_API_KEY=your_penlo_api_key_here

10 Other MCP clients

Windsurf, Zed, Cline, Continue, and Gemini desktop apps all support MCP. The config shape matches the Cursor or VS Code example above — find your client's MCP config docs and drop in the same command / args / env block.

If your client supports MCP and Penlo doesn't work after configuration, let us know at hello@penlo.app with the client name and we'll help you get it running.

11 Troubleshooting

12 Privacy & what gets shared

When you use Penlo MCP, the AI client sends a search query (e.g. "flat white prices") to Penlo's server, and Penlo returns matching OCR text from your notebooks. The AI client then uses that text to compose its response.

A few specifics worth knowing:

• Your handwritten content reaches the AI provider. Whatever Claude or ChatGPT returns to you is composed using the OCR text Penlo sent. That text is part of the conversation and follows the AI provider's data handling policy.
• Penlo authenticates every request. Each request must include a valid Penlo API key. Without it, no data is returned.
• API keys are scoped per user. A key only ever returns the notebooks of the user it belongs to. There's no shared index.
• You can revoke access anytime. Generate a new key in Settings → API to invalidate the old one. Or uninstall the connector from the client side.

For full details, see the Penlo Privacy Policy.

13 Support

Run into something this guide doesn't cover? We'd like to know.