Devon

DEVONthink MCP server for Claude Code. Zero-config setup — one command and you're done.

33 tools for full DEVONthink integration — search, CRUD, AI, tags, smart groups, email threading, and more. All MIT-licensed, zero external dependencies beyond the MCP SDK.

Quick start

If you have Claude Code, just ask:

"Hey Claude, clone Devon from github.com/mnott/Devon and set it up for me"

Claude will clone the repo, build it, configure ~/.claude.json, and enable the server. Restart Claude Code and all 33 DEVONthink tools are available.

What it provides

With this server running, Claude Code can:

• Search and browse all open DEVONthink databases
• Read document content (PDFs, Markdown, plain text, HTML, rich text)
• Create, update, and delete records
• Move, replicate, duplicate, and convert records across groups
• Add and remove tags, classify documents, manage metadata
• Ask DEVONthink's built-in AI about documents and create summaries
• Cross-reference emails with archived documents
• List and navigate database groups
• List smart groups and smart rules (not accessible via AppleScript)
• Parse EML headers for email thread correlation
• Read and copy column layout configurations

Requirements

• macOS (DEVONthink is macOS-only)
• DEVONthink 3 or 4 installed and running
• Node.js >= 18
• Claude Code

Installation

Option 1: Ask Claude (recommended)

In Claude Code, ask Claude to set it up:

"Clone Devon from github.com/mnott/Devon into ~/dev/ai and configure it"

Claude clones, builds, configures ~/.claude.json, and enables the MCP server.

Option 2: Setup wizard

npx @tekmidian/devon setup

Interactive CLI that checks prerequisites, configures ~/.claude.json, and enables the server.

Option 3: Clone and build

git clone https://github.com/mnott/Devon ~/dev/ai/devon
cd ~/dev/ai/devon
npm install
npm run build
node dist/index.js setup

Manual configuration

If you prefer to configure Claude Code manually, add this to the mcpServers section of ~/.claude.json:

"devonthink": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@tekmidian/devon", "serve"],
  "env": {}
}

Or if you have it installed locally:

"devonthink": {
  "type": "stdio",
  "command": "node",
  "args": ["/path/to/devon/dist/index.js", "serve"],
  "env": {}
}

Restart Claude Code after editing ~/.claude.json.

Tools

All 33 tools organized by category.

Application

Database

Records

Groups

Search

Tags

Web

Intelligence

AI

Custom extensions

These five tools extend the core DEVONthink scripting API with functionality not available through AppleScript.

Usage

Once configured, Claude Code has access to all DEVONthink tools automatically. DEVONthink must be running with at least one database open.

Example prompts:

• "Search my DEVONthink databases for notes about the Q3 budget"
• "Find the email from John about the contract and show me related documents"
• "Create a new markdown note in my Inbox with today's meeting notes"
• "List all documents tagged 'todo' in my Ablegen database"
• "Read the content of the PDF I imported yesterday"
• "List my smart groups"
• "Parse the headers from this .eml file to find its thread ID"
• "Ask DEVONthink's AI to summarize these documents"

Custom tool reference

list_smart_groups

Parses ~/Library/Application Support/DEVONthink/SmartGroups.plist and returns all smart groups with their name, UUID, sync date, and UseUUIDKey flag.

Key limitation: Smart groups are not accessible via the DEVONthink AppleScript scripting dictionary. This tool is the only programmatic way to enumerate them.

Parameters: none

Returns:

Each entry in smartGroups:

list_smart_rules

Parses ~/Library/Application Support/DEVONthink/SmartRules.plist and returns all smart rules with name, UUID, enabled state, execution metadata, and sync date.

Parameters: none

Returns:

Each entry in smartRules:

parse_eml_headers

Reads an RFC 2822 .eml file and extracts the MIME headers needed for email thread correlation.

Handles CRLF and LF line endings, folded headers (continuation lines), and RFC 2047 encoded words in Subject, From, and To fields.

Only reads the first 64 KB of the file since headers are always at the start.

Parameters:

Returns:

get_column_layout

Reads the column layout for a named smart group or smart rule from ~/Library/Preferences/com.devon-technologies.think.plist.

Returns the ordered visible columns, all table view columns (visible and hidden), and column widths. Supports partial name matching.

Parameters:

Returns:

copy_column_layout

Copies the column layout from one smart group or smart rule to another. All layout keys are written atomically using Python's plistlib.

DEVONthink must be restarted (or the smart group window closed and reopened) for the change to take effect.

Parameters:

Workflows

Smart group discovery and content querying

Smart groups are virtual views defined by search criteria — they are not part of the AppleScript scripting dictionary. Use this two-step pattern:

Step 1: Enumerate all smart groups.

list_smart_groups

Step 2: Query the contents using search with groupUuid.

search
  query: ""
  groupUuid: "4A469368-94FD-46D3-9A62-ED7C24D822D8"

Note: list_group_content with a smart group UUID returns email Message-IDs in the uuid field (not DEVONthink record UUIDs). Use search with groupUuid instead — it returns proper records with dates and correct UUIDs.

Email thread correlation

To link a live email thread back to its archived copy in DEVONthink, use a three-tier matching strategy:

Tier 1 — Thread ID match (highest precision)

get_record_properties  uuid: <record_uuid>
parse_eml_headers      filePath: "/path/to/archived/email.eml"

Use messageId, inReplyTo, and references to correlate precisely.

Tier 2 — Subject and sender match

search  query: "kind:email subject:\"Contract renewal\" from:jane@example.com"

Strip Re:, Fwd:, AW:, WG: prefixes before searching.

Tier 3 — Subject only (broadest)

search  query: "kind:email subject:\"Contract renewal\""

Column layout management

get_column_layout   name: "Archivieren - Jobs"
copy_column_layout  sourceName: "Archivieren - Jobs"  targetName: "New Smart Group"

Close and reopen the smart group window (or restart DEVONthink) after copying.

DEVONthink search syntax

The search tool supports these operators:

Combining operators:

kind:email from:@company.com subject:"compensation" date:2023-01-01~2024-12-31

How it works

devon is a standalone MCP server built on @modelcontextprotocol/sdk. All 33 tools are implemented from scratch under the MIT license with no external dependencies beyond the MCP SDK.

The tools communicate with DEVONthink via JXA (JavaScript for Automation) executed through osascript. A shared JXA executor handles script construction, escaping, and result parsing. The custom tools (smart groups, smart rules, column layouts) use PlistBuddy and Python's plistlib to read DEVONthink preference and data files directly.

Compatible with both DEVONthink 3 and DEVONthink 4, with automatic app name detection.

Troubleshooting

"DEVONthink not found" Make sure DEVONthink 3 or 4 is installed in /Applications and running.

"No databases found" Open at least one DEVONthink database before using the MCP tools.

Tools not appearing in Claude Code

1. Verify ~/.claude.json has the devonthink entry
2. Restart Claude Code (not just a new session — fully quit and reopen)
3. Check that DEVONthink is running

AppleScript errors Grant Claude Code (or Terminal) Automation permissions in System Settings > Privacy & Security > Automation.

list_smart_groups returns no results or error The plist format varies between DEVONthink versions. Use plutil -p ~/Library/Application\ Support/DEVONthink/SmartGroups.plist to inspect the raw format and report an issue.

get_column_layout returns "no layout found" The smart group does not yet have a custom column layout saved. Use copy_column_layout to copy a layout from another smart group that already has one configured.

Credits

This project was inspired by dvcrn's mcp-server-devonthink, which demonstrated the potential of DEVONthink MCP integration. Version 3.0.0 is a clean-room rewrite — all 33 tools are independently implemented under the MIT license.

License

MIT