Distill MCP

Open-source MCP bridge for Distill: let Claude, Cursor and other MCP clients rename your files based on their content. Works with Claude, OpenAI, Gemini, Ollama or Apple's on-device models. Runs locally on your Mac.

GitHub

दस्तावेज़

Distill MCP Server

Let Claude, Cursor, or any MCP client rename files for you — automatically, based on content.

This is the official Model Context Protocol bridge for Distill — a native macOS app that uses AI (Distill Cloud, or your own Claude, OpenAI or Gemini access, or a local Ollama model) to read your files and rename them with descriptive, consistent names. No more IMG_4521.jpg or Scan_003.pdf — get 250401 Invoice Telekom.pdf instead.

You need the Distill app installed and running. This MCP server is a stdio→HTTP bridge — the actual file analysis happens in the app. Get Distill at store.juergenkoller.software/apps/distill.

The Distill version from the website already contains this bridge as distill-mcp-server, together with its offline manual. Build from this repository only if you want to audit or modify the bridge. The Mac App Store version has neither the REST API nor the MCP server.

What you can do

"Claude, look at the 47 PDFs in ~/Downloads, rename them based on content, but show me the suggestions first."

The MCP server exposes 13 tools:

Tool	What it does
`rename_files`	Analyze file content with AI and rename with descriptive names
`suggest_names`	Suggest new names without renaming (preview mode)
`revert_rename`	Undo a previous rename
`get_rename_history`	Show the rename history (timestamps, before/after, AI provider used)
`watch_folder`	Add a folder to auto-monitoring (new files get renamed in the background)
`process_existing_files`	Process the files already lying in a watched folder
`queue_status`	Progress of automatic processing: detected, done, open, renamed, failed
`app_status`	Current state, AI provider, credits left, watched folders
`set_provider`	Switch AI provider — Distill Cloud (default, uses credits), or in the website version your own Claude, OpenAI or Gemini access, or Ollama (local)
`get_rules`	Show naming rules (date format, casing, categories, custom templates)
`set_rules`	Update naming rules
`search_manual`	Search the Distill user manual (works offline, even without the app running)
`get_manual_section`	Read one chapter of the manual as Markdown

Distill reads PDFs, images (via OCR), Office documents, emails, HTML, RTF, and media files. It extracts date, category, description, sender, and amounts — then builds filenames using your configurable rules.

Installation

Prerequisites

macOS 15 (Sequoia) or later — Distill's own requirement
Distill app installed and running — get it here (website version; free, 100 starter credits, then pay-per-use from €1.99 per 100 name suggestions)
Terms of Use and Privacy Policy accepted once in the Distill window — until then the API answers only status requests
Swift 5.9+ (Xcode 15+) only if building from source

Use the bridge inside the app (recommended)

/Applications/Distill.app/Contents/MacOS/distill-mcp-server

It always matches the installed app version and finds the offline manual on its own.

Build from source

git clone https://github.com/juergenkoller-software/distill-mcp.git
cd distill-mcp
swift build -c release
# Binary: .build/release/DistillMCP

Pre-built binary

Not needed on a Mac: the website version of Distill ships the bridge (see above). The binary attached to Releases is a static Linux x86_64 build for container-based MCP registries such as Glama; it does not run on macOS.

Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "distill": {
      "command": "/Applications/Distill.app/Contents/MacOS/distill-mcp-server",
      "env": {
        "DISTILL_API_PORT": "43821",
        "DISTILL_API_TOKEN": "only-if-set-in-distill"
      }
    }
  }
}

DISTILL_API_TOKEN is needed only if you set a token in Distill → Settings → API. Without a token, Distill accepts connections from your own Mac only.

Claude Code

claude mcp add distill /Applications/Distill.app/Contents/MacOS/distill-mcp-server \
  --env DISTILL_API_PORT=43821

Cursor / other MCP clients

Same pattern — DistillMCP is a stdio MCP server, configured via the two env vars above.

How it works

┌────────────────┐  JSON-RPC stdio   ┌────────────────┐  HTTP+Bearer   ┌────────────────┐
│  Claude/Cursor │ ───────────────►  │  DistillMCP    │ ─────────────► │  Distill.app   │
│  (MCP client)  │ ◄───────────────  │   (this repo)  │ ◄───────────── │  (port 43821)  │
└────────────────┘                   └────────────────┘                └────────────────┘

The bridge reads JSON-RPC 2.0 requests from stdin, translates each tool call into a request to Distill's local REST API (http://localhost:43821/v1/…), and writes responses back to stdout. All AI calls (Distill Cloud, Claude, OpenAI, Gemini, Ollama), file reading (OCR, PDF extraction, Office parsing), credit tracking, and naming logic happen inside the Distill app.

This split lets the wire format stay open-source (audit it, sandbox it, run it through any MCP runtime) while the heavy lifting stays in the app.

Environment variables

Variable	Default	Description
`DISTILL_API_PORT`	`43821`	Port of Distill's local HTTP server (Distill → Settings → API)
`DISTILL_API_TOKEN`	(none)	Bearer token — only if set in Distill → Settings → API
`DISTILL_MANUAL_JSON`	(next to the binary)	Path to `distill-manual.json` for a bridge built from source: `/Applications/Distill.app/Contents/Resources/distill-manual.json`

Errors and trace logs go to stderr so they don't pollute the JSON-RPC stdout channel.

Errors

Every refusal comes back as an MCP error (isError: true) with a sentence the agent can act on:

Situation	What the bridge reports
Distill not running, API off, or Mac App Store version	Distill is not reachable at `http://localhost:<port>`; open Distill and check Settings → API
Token wrong or missing (HTTP 401)	Set `DISTILL_API_TOKEN` to the token in Distill → Settings → API
Legal texts not accepted (HTTP 403 `legal_not_accepted`)	The user opens the Distill window and accepts in the “Legal Notice” sheet; an agent cannot do this
Any other HTTP error	Status code and Distill's error text, e.g. `engine not ready` while the app starts

Before version 0.2.0 the bridge ignored the HTTP status, so these refusals looked like successful calls.

About Distill

Distill is an AI file manager for macOS that automatically renames files based on content analysis. Highlights:

No subscription — free app, pay-per-use credits (100 free / 100 for €1.99 / 400 for €4.99 / 1,000 for €8.99)
Distill Cloud by default — credits, no sign-up; in the website version also your own Claude, OpenAI or Google Gemini access (no credits used) or Ollama (local, no API key)
Reads everything — PDFs, images (OCR), Office docs, emails, HTML, RTF, media files
Local-only mode with Ollama — nothing leaves your Mac
Configurable NameBuilder — date formats, casing, categories, custom templates
Folder monitoring — drop files in, get them renamed automatically
REST API + Swagger UI — for non-MCP automation
MCP server (this repo) — for Claude/AI agents, in the website version
24 languages
Available on the Mac App Store and as a direct download — the REST API and MCP server ship with the direct download

→ Get Distill at store.juergenkoller.software

License

MIT — see LICENSE. Bridge is open source; the Distill app is commercial (free-to-try with pay-per-use credits).

Issues & support

Bridge bugs: open an issue
App support: support@juergenkoller.software

Built by Juergen Koller Software GmbH.