@penloapp/mcp-server

MCP (Model Context Protocol) server for Penlo — search your handwritten e-ink notes from any AI assistant that speaks MCP.

Works with Claude, ChatGPT, Cursor, VS Code, Claude Code, Windsurf, Zed, and others.

Claude Desktop users: prefer the one-click .mcpb installer at https://penlo.app/mcp-guide. This npm package is for non-Claude MCP clients.

Prerequisites

• A Penlo account on the Power plan
• A Penlo API key — generate one in Penlo at Settings → API
• Node.js 18 or newer

Tools

This server exposes three tools to your AI assistant:

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

Setup

Cursor

Add to ~/.cursor/mcp.json (macOS / Linux) or %USERPROFILE%\.cursor\mcp.json (Windows):

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

Restart Cursor.

VS Code (GitHub Copilot)

Add to .vscode/mcp.json (workspace) or your user-level mcp.json. Note: VS Code uses servers, not mcpServers.

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

Reload the window.

ChatGPT (Plus, Pro, Business, Enterprise)

In ChatGPT settings, enable Developer Mode under Connectors, then add a new MCP server with:

• Command: npx
• Args: -y @penloapp/mcp-server
• Environment variable: PENLO_API_KEY=your_penlo_api_key_here

Claude Code

claude mcp add penlo \
  --command npx \
  --args "-y @penloapp/mcp-server" \
  --env PENLO_API_KEY=your_penlo_api_key_here

Configuration

| Variable | Required | Default | Description | |---|---|---|---| | PENLO_API_KEY | ✅ Yes | — | Your Penlo API key. Generate at penlo.app → Settings → API. | | PENLO_API_URL | No | https://notes.penlo.app/mcp | Override the Penlo MCP endpoint (advanced). |

Try it

In your AI assistant, ask something like:

• "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."

For more example prompts and a full install walkthrough, see https://penlo.app/mcp-guide.

Privacy & security

• Your API key is scoped to your own notes only.
• Penlo only returns notebooks where OCR has completed.
• The MCP server runs locally on your machine; it talks to Penlo's API directly, not through any third party.
• See penlo.app/privacy for full details.

Troubleshooting

Missing required environment variable PENLO_API_KEY Pass PENLO_API_KEY in the env block of your MCP client's config.

Invalid API key The key was rotated or copied with whitespace. Generate a new one in Penlo at Settings → API.

upgrade_required MCP access requires the Power plan. Upgrade at penlo.app.

No results from search_notes OCR may still be processing. Penlo's MCP server only returns notebooks where OCR has completed. Check sync status in your Penlo dashboard.

Support

• Email: [email protected]
• Website: https://penlo.app

License

MIT