Devon

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

The focused complement to DEVONthink 4.3's built-in MCP server. DEVONthink now ships its own MCP server covering generic search, reads, and CRUD — so Devon deliberately exposes only the 15 tools where it does something the native server can't: smart-group and smart-rule introspection, column layouts, .eml header parsing, richer web capture, incremental tagging, and parameterized AI. All MIT-licensed, zero external dependencies beyond the MCP SDK. Run both servers side by side.

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 Devon's tools are available alongside DEVONthink's built-in MCP server.

What it provides

Devon fills the gaps in DEVONthink's built-in MCP server. With it running, Claude Code can:

Enumerate smart groups and smart rules (read straight from DEVONthink's plists — the native scripting API doesn't expose these)
Read and copy column layouts for smart groups and rules
Parse .eml MIME headers (Message-ID, References, In-Reply-To) for email thread correlation
Capture web pages with rich options (format, readability, custom user-agent, referrer, PDF options)
Add and remove tags incrementally (the native tag tool only replaces the full set)
Ask DEVONthink's AI with model / engine / temperature control and create real summary records

For generic full-text search, record reads, and CRUD, use DEVONthink's built-in MCP server — Devon does not duplicate it. See Relationship to the built-in server.

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.

Relationship to the built-in DEVONthink MCP server

DEVONthink 4.3 ("Herschel", released 2026-05-21) ships its own MCP server inside the app bundle (/Applications/DEVONthink.app/Contents/Library/LoginItems/DEVONthink MCP.app), also reachable over HTTP. It exposes ~59 tools covering generic search, reads, CRUD, OCR, transcription, annotations, custom metadata, reminders, the link graph, and DOI/CrossRef research.

Devon does not compete with it. Run both:

Built-in devonthink server — everything generic: search_records, get_record_text, get_record_properties, create_record, move_record, batch operations, and all the native-only capabilities above.
Devon — the 15-tool complement below: smart-group / smart-rule introspection, column layouts, .eml headers, richer web capture, incremental tagging, and parameterized AI — the things the built-in server can't do.

A full tool-by-tool capability differential lives in Notes/.

Tools

15 tools, each chosen because it does something DEVONthink's built-in MCP server can't (or does better).

Smart groups, rules & layouts

Read directly from DEVONthink's plists — the native scripting API does not expose these.

Tool	Description
`list_smart_groups`	Enumerate all smart groups (sync UUID, `UseUUIDKey`)
`list_smart_rules`	Enumerate all smart rules (enabled state, `indexOffset`, `lastExecution`)
`get_column_layout`	Read column layout (order, visible columns, widths) for a smart group or rule
`copy_column_layout`	Copy a column layout from one smart group/rule to another

Email

Tool	Description
`parse_eml_headers`	Extract Message-ID, References, In-Reply-To, etc. from .eml files

Web capture

Tool	Description
`create_from_url`	Capture a URL with `format`, `readability`, `userAgent`, `referrer`, `pdfOptions` (richer than native `capture_web_page`)

Tags (incremental)

The native set_record_tags replaces the entire tag set; these add/remove individual tags.

Tool	Description
`add_tags`	Add tags to a record without touching existing ones
`remove_tags`	Remove specific tags from a record

AI

Tool	Description
`ask_ai_about_documents`	Ask DEVONthink's AI with `model` / `engine` / `temperature` control (native `chat_response` is minimal)
`create_summary_document`	Create a real DEVONthink summary record (native only returns text)
`check_ai_health`	Check if DEVONthink's AI features are available
`get_ai_tool_documentation`	Get documentation for DEVONthink's AI capabilities

Lookup & database

Tool	Description
`lookup_record`	Look up records — including by `tags` or `contentHash` (modes native lacks)
`get_record_by_identifier`	Focused single-call fetch by UUID/identifier
`current_database`	Get the frontmost database (no native equivalent)

Delegated to the built-in server

Devon intentionally does not ship these — DEVONthink's built-in MCP server does them as well or better (often with batch uuids support and its full query DSL): full-text search_records, classify_record, find_similar_records, get_record_text / extract_record_content, get_record_properties, create_record, update_record, update_record_content, move_record, duplicate_record, replicate_record, convert_record, trash_record, get_databases, get_group_tree, get_selected_records, is_running, plus everything native-only (OCR, transcription, annotations, custom metadata, reminders, link graph, DOI/CrossRef research, import/export, merge).

Usage

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

Closed databases are invisible — open them before a "search everything" request

DEVONthink searches only what is open. A closed database produces no hits and no warning, so a "nothing found" answer drawn from a partial set is wrong, not empty — and archives, the databases most likely to be sitting closed, are exactly where history lives.

Devon ships this as part of its MCP instructions, so Claude should now open the missing databases on its own before answering. The procedure:

# 1. what is open, and where do those databases live
osascript -e 'tell application id "DNtp" to get path of every database'

# 2. list *.dtBase2 in those folders — anything not in step 1 is closed

# 3. open each closed one, ONE PER CALL (a large archive can take minutes;
#    batching several opens into one osascript call hits the 120s tool timeout)
osascript -e 'tell application id "DNtp" to open database "/abs/path/Archive.dtBase2"'

# 4. clear any "database was recovered / issues were found" dialog — it blocks
#    the open until dismissed, and the database silently stays out of searches
osascript -e 'tell application "System Events" to tell process "DEVONthink" to get name of windows'

# 5. verify before searching
osascript -e 'tell application id "DNtp" to get name of every database'

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:

Field	Type	Description
`success`	boolean	Whether the operation succeeded
`smartGroups`	array	List of smart group entries
`totalCount`	number	Total number of smart groups found

Each entry in smartGroups:

Field	Type	Description
`name`	string	Display name of the smart group
`uuid`	string	UUID from the `sync.UUID` field — use this with the `search` tool
`syncDate`	string \| null	Last sync date (ISO 8601)
`useUuidKey`	boolean \| null	Whether DEVONthink uses UUID as the key internally

`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:

Field	Type	Description
`success`	boolean	Whether the operation succeeded
`smartRules`	array	List of smart rule entries
`totalCount`	number	Total number of smart rules found

Each entry in smartRules:

Field	Type	Description
`name`	string	Display name of the smart rule
`uuid`	string	UUID from the `sync.UUID` field
`enabled`	boolean \| null	Whether the rule is currently enabled
`indexOffset`	number \| null	Order index within the rules list
`lastExecution`	number \| null	CFAbsoluteTime timestamp of last execution
`syncDate`	string \| null	Last sync date (ISO 8601)
`useUuidKey`	boolean \| null	Whether DEVONthink uses UUID as the key internally

`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:

Parameter	Type	Required	Description
`filePath`	string	yes	Absolute path to the `.eml` file

Returns:

Field	Type	Description
`success`	boolean	Whether parsing succeeded
`filePath`	string	The path that was read
`messageId`	string \| null	The `Message-ID` header value
`inReplyTo`	string \| null	The `In-Reply-To` header value
`references`	string[]	Array of message IDs from the `References` header
`subject`	string \| null	Decoded subject line
`from`	string \| null	Sender address(es)
`to`	string \| null	Recipient address(es)
`cc`	string \| null	CC address(es)
`date`	string \| null	Date string from the header

`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:

Parameter	Type	Required	Description
`name`	string	yes	Display name of the smart group or smart rule
`uuid`	string	no	UUID fallback if name lookup fails

Returns:

Field	Type	Description
`success`	boolean	Whether a layout was found
`name`	string	The name that was searched
`resolvedKey`	string	The actual plist key used
`columns`	string[] \| null	Visible columns in display order
`tableViewColumns`	string[] \| null	All column identifiers (visible + hidden)
`widths`	object \| null	Map of column identifier to width
`keysFound`	string[]	Which plist keys were present

`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:

Parameter	Type	Required	Description
`sourceName`	string	yes	Name of the source smart group
`targetName`	string	yes	Name of the target smart group
`sourceUuid`	string	no	UUID fallback for the source
`targetUuid`	string	no	UUID for the target (layout written under UUID key)

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 the built-in server's search_records with group_uuid.

search_records            (native devonthink server)
  query: ""
  group_uuid: "4A469368-94FD-46D3-9A62-ED7C24D822D8"

Note: Devon supplies the smart-group UUID (via list_smart_groups); the native search_records tool scopes to it with group_uuid and returns proper DEVONthink records with dates and correct UUIDs. Devon no longer ships its own search / list_group_content — the built-in server covers those.

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:

Operator	Example	Description
`kind:`	`kind:email`	Filter by record type
`name:`	`name:"offer letter"`	Match filename or subject
`subject:`	`subject:"interview"`	Email subject field
`from:`	`from:recruiter@co.com`	Sender address
`to:`	`to:user@example.com`	Recipient address
`text:`	`text:"stock options"`	Full-text content search
`tags:`	`tags:jobs`	Tagged records
`date:`	`date:2024-01-01~`	Date range (`~` = after)
Quotes	`"exact phrase"`	Exact phrase match
AND/OR	`from:x OR from:y`	Boolean 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 15 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

Verify ~/.claude.json has the devonthink entry
Restart Claude Code (not just a new session — fully quit and reopen)
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 was a clean-room rewrite; from v4.0.0 Devon narrows to the 15 tools that complement DEVONthink 4.3's own built-in MCP server rather than duplicating it. All tools are independently implemented under the MIT license.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github		.github
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Devon

Quick start

What it provides

Requirements

Installation

Option 1: Ask Claude (recommended)

Option 2: Setup wizard

Option 3: Clone and build

Manual configuration

Relationship to the built-in DEVONthink MCP server

Tools

Smart groups, rules & layouts

Email

Web capture

Tags (incremental)

AI

Lookup & database

Delegated to the built-in server

Usage

Closed databases are invisible — open them before a "search everything" request

Custom tool reference

list_smart_groups

list_smart_rules

parse_eml_headers

get_column_layout

copy_column_layout

Workflows

Smart group discovery and content querying

Email thread correlation

Column layout management

DEVONthink search syntax

How it works

Troubleshooting

Credits

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`list_smart_groups`

`list_smart_rules`

`parse_eml_headers`

`get_column_layout`

`copy_column_layout`