Connect Penlo to Claude

Search your handwritten notes from Claude, ChatGPT, and any AI assistant

Power plan required

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.

Each user's API key is scoped to their own notes only. The MCP server filters every query by the authenticated user — there's no shared index and no cross-user access.

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.

OCR must finish before MCP can read a notebook. Notebooks that failed OCR or are still pending won't appear in search results. Check the status badge in your Penlo dashboard.

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.

If you lose your key, generate a new one and update each client. Old keys can be revoked anytime from Settings → API.

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.

Download the Penlo extension

Download .mcpb
~5 MB · macOS, Windows, Linux · Claude Desktop 0.10+

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.

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.

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.

6. Install in ChatGPT

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

Step 1 — Install Node.js (if you don't have it)

Check by running node --version in a terminal. If not installed, get it from nodejs.org.

Step 2 — Add the connector

1. In ChatGPT (web), click your profile icon → Settings → Connectors.
2. Toggle on Developer Mode.
3. Click Add MCP server and fill in:

Name:    Penlo
Command: npx
Args:    -y @penloapp/mcp-server

Environment variables:
  PENLO_API_URL = https://notes.penlo.app/mcp
  PENLO_API_KEY = your_penlo_api_key_here

7. Install in Cursor

Reference your handwritten notes while you code. Cursor reads MCP config from a JSON file.

Config file location

• macOS / Linux: ~/.cursor/mcp.json
• Windows: %USERPROFILE%\.cursor\mcp.json

Add the Penlo entry

{
  "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"
      }
    }
  }
}

Restart Cursor. Penlo tools appear in Cursor's chat tool list.

8. Install in VS Code

Use Penlo from GitHub Copilot Chat inside Visual Studio Code. Create .vscode/mcp.json in your project root:

{
  "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"
      }
    }
  }
}

Note: VS Code uses servers (not mcpServers like Cursor). Run Developer: Reload Window from the command palette.

9. Install in Claude Code

If you use Claude Code (the CLI), register Penlo with a single command:

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.

11. Troubleshooting

12. Privacy & what gets shared

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

• Your handwritten content reaches the AI provider. The OCR 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 API key. Without it, no data is returned.
• API keys are scoped per user. A key only returns the notebooks of the user it belongs to.
• You can revoke access anytime. Generate a new key in Settings → API to invalidate the old one.

For full details, see the Penlo Privacy Policy.

13. Support

Run into something this guide doesn't cover?

Email: hello@penlo.app
Release notes: penlo.app/changelog