@penloapp/mcp-server 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michał Włosik EFC (Penlo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# @penloapp/mcp-server
+
+MCP (Model Context Protocol) server for [Penlo](https://penlo.app) — 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](https://penlo.app) 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):
+
+```json
+{
+  "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`.
+
+```json
+{
+  "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
+
+```bash
+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](https://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: <hello@penlo.app>
+- Website: <https://penlo.app>
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const PENLO_API_URL = process.env.PENLO_API_URL || "https://notes.penlo.app/mcp";
+const PENLO_API_KEY = process.env.PENLO_API_KEY;
+
+if (!PENLO_API_KEY) {
+  console.error(
+    "[penlo-mcp] Missing required environment variable PENLO_API_KEY. " +
+    "Generate one in Penlo at Settings → API."
+  );
+  process.exit(1);
+}
+
+const USER_AGENT = "penlo-mcp/1.2.0";
+
+async function penloFetch(path, body) {
+  const base = PENLO_API_URL.replace(/\/+$/, "");
+  const url = base + (path.startsWith("/") ? path : "/" + path);
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${PENLO_API_KEY}`,
+      "User-Agent": USER_AGENT,
+    },
+    body: JSON.stringify(body ?? {}),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(
+      `Penlo API error ${res.status}: ${text || res.statusText}`
+    );
+  }
+  return res.json();
+}
+
+const server = new Server(
+  { name: "penlo-mcp", version: "1.2.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "search_notes",
+      description:
+        "Search inside the OCR'd CONTENT of your handwritten notes. Use this when the user is looking for something they WROTE on the page — concepts, ideas, quotes, names mentioned in the body of their notes. Do NOT use this to find a notebook by its title or filename; use find_notebook for that.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description:
+              "Words or phrases that should appear in the handwritten content (e.g. 'machine learning', 'protein folding', 'reminder about taxes').",
+          },
+          limit: {
+            type: "number",
+            description: "Max results to return (default 10, max 20).",
+            default: 10,
+            minimum: 1,
+            maximum: 20,
+          },
+          start_date: {
+            type: "string",
+            description:
+              "Optional: only include notes created after this ISO 8601 date.",
+          },
+          end_date: {
+            type: "string",
+            description:
+              "Optional: only include notes created before this ISO 8601 date.",
+          },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "find_notebook",
+      description:
+        "Find notebooks by TITLE or FILENAME. Use this when the user names a specific notebook ('open my Q4 planning notebook', 'find the meeting notes file', 'is there a notebook called Ideas.pdf?'). Matches against both the user-set display name and the original PDF filename, case-insensitive, substring match. Returns notebook metadata, not page content.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description:
+              "Title or filename to look for (e.g. 'Q4 planning', 'meeting notes', 'ideas.pdf'). Partial matches are fine.",
+          },
+          limit: {
+            type: "number",
+            description: "Max results to return (default 10, max 20).",
+            default: 10,
+            minimum: 1,
+            maximum: 20,
+          },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "list_recent_notes",
+      description:
+        "List the most recently synced notebooks. Use this when the user asks what they've been working on lately, wants a chronological overview, or has no specific search term in mind.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          limit: {
+            type: "number",
+            description: "Number of notebooks to return (default 10, max 20).",
+            default: 10,
+            minimum: 1,
+            maximum: 20,
+          },
+        },
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    if (name === "search_notes") {
+      const data = await penloFetch("/search", {
+        query: args.query,
+        limit: Math.min(args.limit ?? 10, 20),
+        start_date: args.start_date,
+        end_date: args.end_date,
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+      };
+    }
+
+    if (name === "find_notebook") {
+      const data = await penloFetch("/find", {
+        query: args.query,
+        limit: Math.min(args.limit ?? 10, 20),
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+      };
+    }
+
+    if (name === "list_recent_notes") {
+      const data = await penloFetch("/recent", {
+        limit: Math.min(args?.limit ?? 10, 20),
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+      };
+    }
+
+    return {
+      content: [{ type: "text", text: `Unknown tool: ${name}` }],
+      isError: true,
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error calling ${name}: ${err.message ?? String(err)}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[penlo-mcp] Server running on stdio");

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@penloapp/mcp-server",
+  "version": "1.2.0",
+  "description": "MCP server for Penlo — search your handwritten e-ink notes from Claude, ChatGPT, Cursor, VS Code, and any MCP-compatible AI assistant.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "penlo-mcp-server": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "penlo",
+    "notes",
+    "handwriting",
+    "ocr",
+    "claude",
+    "chatgpt",
+    "cursor",
+    "boox",
+    "remarkable",
+    "supernote",
+    "e-ink"
+  ],
+  "author": "Penlo <hello@penlo.app>",
+  "license": "MIT",
+  "homepage": "https://penlo.app",
+  "bugs": {
+    "url": "mailto:hello@penlo.app"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/penloapp/mcp-server.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}