Noteker

Noteker is a macOS MCP server that converts handwritten PDF notes into clean Markdown using Claude Vision. Give it a PDF, get back structured text — no OCR engine, no separate models, no setup beyond an Anthropic API key.

Designed for notes exported from Noteshelf3 on iPad, but works with any handwritten PDF.

---

How it works

Claude ──MCP stdio──▶ noteker
                          │
               ┌──────────▼──────────┐
               │  PyMuPDF             │
               │  PDF → PNG per page  │
               └──────────┬──────────┘
                          │
               ┌──────────▼──────────┐
               │  Claude Vision API   │
               │  transcribe + format │
               └──────────┬──────────┘
                          │
               clean Markdown ──▶ Claude

Each page is rendered to an image and sent to Claude Vision, which transcribes the handwriting and formats it as Markdown in a single pass. Blank pages are skipped automatically. Pages are processed in batches of at most 5 — requests spanning more pages are automatically split into sequential batches and stitched back into one combined Markdown result.

Both tools are read-only: they never modify the source PDF or any other file.

---

Tools

Tool	Description
noteker_process_pdf(file_path, note_context="", page_start=None, page_end=None)	Transcribe a local PDF of handwritten notes. Returns clean Markdown. note_context is an optional hint (e.g. "team meeting 2025-06-20") that helps Claude resolve ambiguous words. page_start / page_end are 1-based inclusive page bounds — omit both to process the whole document (capped at max_pages). Internally, pages are sent to Claude Vision in batches of at most 5 regardless of range size.
noteker_status()	Return version, config path, and whether the API key is set.

---

Installation

As a Claude Desktop extension (recommended)

1. Download the latest noteker-x.y.z.mcpb from the Releases page.
2. Double-click it (or drag it into Claude Desktop → Settings → Extensions) to install.
3. When prompted, paste your Anthropic API key — Claude Desktop stores it securely and passes it to Noteker as ANTHROPIC_API_KEY.

That's it — no separate config file or MCP registration step needed. Extra settings (model, max_pages, dpi) are still read from ~/.noteker/config/settings.yaml if you want to override the defaults (see Configuration).

From source

Requirements: Python 3.11+, macOS

git clone https://github.com/andras-tkcs/noteker
cd noteker
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Copy and edit the config:

cp config/settings.yaml.example config/settings.yaml
# Edit config/settings.yaml — add your Anthropic API key

Register Noteker with Claude (see MCP registration) using the path .venv/bin/noteker.

---

Configuration

Config file location:

Context	Path
Claude Desktop extension	~/.noteker/config/settings.yaml
From source	config/settings.yaml (next to pyproject.toml)
Override	Set NOTEKER_CONFIG_DIR environment variable

anthropic:
  # API key from console.anthropic.com → API Keys
  # Can also be set via the ANTHROPIC_API_KEY environment variable.
  api_key: sk-ant-api03-...
  # Model used for transcription.
  # claude-sonnet-4-6 is recommended. Use claude-opus-4-8 for very difficult handwriting.
  model: claude-sonnet-4-6

noteker:
  # Maximum pages to process per PDF (safety cap).
  max_pages: 50
  # Rendering resolution. 150 DPI works well for most handwriting.
  # Increase to 200 if the handwriting is very small.
  dpi: 150

logging:
  level: INFO

Anthropic API key

Create a key at console.anthropic.com → API Keys. It looks like sk-ant-api03-....

You can set it in settings.yaml as shown above, or export it as an environment variable — Noteker checks both:

export ANTHROPIC_API_KEY=sk-ant-api03-...

Adding the export to ~/.zshrc means you never need it in the config file.

---

MCP registration

The Claude Desktop extension registers itself — no manual JSON editing needed.

For Claude Code CLI, add Noteker to the project's .claude/settings.json (the .mcpb format doesn't apply to Claude Code, which always uses a direct command path):

{
  "mcpServers": {
    "noteker": {
      "command": "/absolute/path/to/noteker/.venv/bin/noteker"
    }
  }
}

Or, with the API key passed directly instead of via settings.yaml:

{
  "mcpServers": {
    "noteker": {
      "command": "/absolute/path/to/noteker/.venv/bin/noteker",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-api03-..."
      }
    }
  }
}

After saving the config, restart Claude Code (or reload MCP servers) and run noteker_status() to confirm the setup.

---

Usage

A typical session with both Noteker and Loopline:

# 1. Find the PDF on Google Drive (via loopline)
drive_list_files(query="name contains 'Meeting Notes' and mimeType='application/pdf'")
→ file_id: "1aBcD..."

# 2. Download it locally (via loopline — drive_save_to_path)
drive_save_to_path(file_id="1aBcD...")
→ /Users/you/Downloads/Meeting Notes 2025-06-20.pdf

# 3. Transcribe the handwriting (via noteker)
noteker_process_pdf(
  file_path="/Users/you/Downloads/Meeting Notes 2025-06-20.pdf",
  note_context="product team standup"
)
→ ## Page 1
  ### Action items
  - Follow up with design on the onboarding flow
  ...

Noteker is source-agnostic — any local PDF works, regardless of how it got there.

---

Building the .mcpb

./scripts/build_mcpb.sh

Output: noteker-<version>.mcpb. The build script creates a virtual environment at server/venv with all dependencies installed, so the extension has no runtime dependency on uv or pip. It still links against the Python 3.13 framework install used to build it, and PyMuPDF ships arch-specific wheels — build on the same OS/CPU architecture (arm64 macOS) you're targeting.

---

License

Apache 2.0 — see LICENSE.