Distill MCP
Distill MCP bridges MCP clients to the local Distill macOS app for AI file-content analysis and renaming management.
Rename files by content or suggest names without renaming, using optional templates.
Revert a rename and show rename history.
Add folders to auto-monitoring and, per README, process existing files and check queue progress.
Check app status/settings, AI provider, credits, and watched folders.
Switch AI provider (Claude, OpenAI, Gemini, Ollama, Apple) with optional model/API key/endpoint.
Get or update naming rules: format, date format, casing, categories, prefix, suffix, separator.
Search/read the offline manual (README only; not in the provided schema).
Allows using Apple Intelligence as an AI provider to analyze file content and generate descriptive filenames via the Distill app.
Allows using Google Gemini as an AI provider to analyze file content and generate descriptive filenames via the Distill app.
Allows using Ollama as a local AI provider to analyze file content and generate descriptive filenames without data leaving the machine.
Allows using OpenAI (e.g., GPT-4o) as an AI provider to analyze file content and generate descriptive filenames via the Distill app.
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 |
| Analyze file content with AI and rename with descriptive names |
| Suggest new names without renaming (preview mode) |
| Undo a previous rename |
| Show the rename history (timestamps, before/after, AI provider used) |
| Add a folder to auto-monitoring (new files get renamed in the background) |
| Process the files already lying in a watched folder |
| Progress of automatic processing: detected, done, open, renamed, failed |
| Current state, AI provider, credits left, watched folders |
| Switch AI provider — Distill Cloud (default, uses credits), or in the website version your own Claude, OpenAI or Gemini access, or Ollama (local) |
| Show naming rules (date format, casing, categories, custom templates) |
| Update naming rules |
| Search the Distill user manual (works offline, even without the app running) |
| 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.
Related MCP server: Readedit
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-serverIt 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/DistillMCPPre-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=43821Cursor / 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 |
|
| Port of Distill's local HTTP server (Distill → Settings → API) |
| (none) | Bearer token — only if set in Distill → Settings → API |
| (next to the binary) | Path to |
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 |
Token wrong or missing (HTTP 401) | Set |
Legal texts not accepted (HTTP 403 | 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. |
Before version 1.1.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.
Available Tools
9 toolsapp_statusA
Gibt den aktuellen App-Status und Einstellungen zurück
Inputs: no named parameters.
get_rename_historyC
Zeigt die Umbenennungs-Historie
Inputs: limit.
get_rulesA
Zeigt die aktuellen Umbenennungsregeln (Format, Datum, Casing, Kategorien)
Inputs: no named parameters.
rename_filesB
Benennt Dateien um: Analysiert den Inhalt mit KI und benennt die Dateien mit beschreibenden Namen um
Inputs: paths (required), template.
revert_renameB
Macht eine Umbenennung rückgängig
Inputs: path (required).
set_providerB
Wechselt den KI-Provider (Claude, OpenAI, Gemini, Ollama, Apple)
Inputs: provider (required), model, apiKey, endpoint.
set_rulesC
Ändert die Umbenennungsregeln
Inputs: casing, format, prefix, suffix, +3 more.
suggest_namesB
Schlägt neue Dateinamen vor ohne umzubenennen
Inputs: paths (required), template.
watch_folderC
Fügt einen Ordner zur Überwachung hinzu
Inputs: path (required), autoRename.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a distinct purpose: status, history, rules (get/set), rename, revert, provider switch, suggestions, and folder watching. No overlapping functions.
All tool names use consistent snake_case with clear verbs (get_, set_, rename_, revert_, suggest_, watch_) and follow a predictable pattern.
9 tools cover the core functionality of an AI-powered file renaming application without being excessive or insufficient.
The tool set includes all essential operations: renaming, reverting, rule management, provider switching, suggestions, history, and folder watching. No obvious gaps.
Maintenance
Related MCP Connectors
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
An agent-first office suite Claude & ChatGPT read and write over one MCP URL.
Your own computer's files from ChatGPT or Claude: folder rules, confirmations and undo.
Related MCP Servers
- AlicenseBqualityBmaintenanceA powerful, security-hardened MCP server for intelligent file organization. Provides high-level atomic tools for organizing files into categories, detecting duplicates, extracting EXIF/ID3 metadata, scheduling automatic organization, and more — for use with Claude, Cursor, and Gemini CLI.26120 npm46MIT
- AlicenseAqualityDmaintenanceMCP server that combines Read+Edit file operations into single tool calls. 80-95% fewer tool calls formulti-file refactoring across Claude, Cursor, Windsurf, and more.315 npm3MIT
- AlicenseBqualityCmaintenanceMCP bridge for PDF Content Search — full-text PDF search with Apple Vision OCR across thousands of documents in under a second from Claude, Cursor, or any MCP client. Advanced filters (date, category, sender, amount), wildcards, boolean operators. Bridge open-source (MIT), PDF Content Search app is commercial with free iOS+Android companion scanner apps.841MIT
- AlicenseAqualityCmaintenanceMCP server for FreezeText — OCR anything on your Mac screen from Claude, Cursor, or any MCP client. Freeze the screen and extract text via Apple Vision (videos, popups, protected PDFs), OCR a region or a base64 image, and manage a searchable capture history. 12 tools. Bridge open-source (MIT), FreezeText app is free.121MIT