hookmark-mcp

MCP server that gives Claude Code (and other MCP clients) full access to Hookmark — the macOS app that creates bidirectional links between files, URLs, emails, notes, and anything else with an address.

Link a PDF to an email. Connect a note to a webpage. Find everything related to a project. All through natural language.

How It Works

The server wraps Hookmark's hook CLI as seven MCP tools. Claude calls them like any other tool — you just talk normally:

• "Link my TODO to that PDF on the desktop"

• "What's connected to this file?"

• "Search hookmark for everything about invoices"

• "Hook whatever's open in Mail to this project"

You never need to remember tool names or parameters.

Quick Start

Prerequisites:

• macOS with Hookmark installed

• Hookmark's hook CLI (gem install hookmark or installed with Hookmark)

• Node.js 18+ or Bun

Install with Claude Code:

Tell Claude:

"Install the hookmark MCP server from github.com/mnott/Hook"

Claude will clone the repo, build it, and add it to your MCP config.

Manual install:

Add to your Claude Code MCP config (~/.claude.json):

Or with Bun:

Restart Claude Code. The tools are ready.

From source (development):

Then point your MCP config to the local build:

Tools at a Glance

User Guide

You never need to remember tool names or parameters — just describe what you want in plain English. Here are the things you can do, organized by what you're trying to accomplish.

Connecting Things

The core of Hookmark is bidirectional links. When you connect two items, each one knows about the other.

"Link my TODO.md to the project requirements PDF on the desktop"

"Connect this source file to the GitHub issue at

"Hook the meeting notes to the presentation slides"

"Link every .ts file in src/ to the architecture document"

You can link files to files, files to URLs, URLs to URLs — anything with an address.

Finding Connections

Once things are linked, you can explore the web of connections from any starting point.

"What's hooked to this file?"

"Show me everything connected to the project plan"

"List all hooks for src/index.ts in verbose format"

"What files are linked to

"Show me all my Hookmark bookmarks"

Omit the item to list everything. Ask for different output formats — paths, markdown links, hook:// URLs, or verbose details with titles and addresses.

Searching

Search across all your Hookmark bookmarks by keyword — it searches both names and URLs.

"Search hookmark for 'invoice'"

"Find all bookmarks related to the quarterly report"

"Search hookmark for anything mentioning 'API design'"

"Search just bookmark names for 'meeting' — don't search URLs"

"Search hookmark for 'budget' but only show files, no emails"

Working with Apps

Hookmark can reach into the frontmost window of any macOS app and grab a reference to whatever's active — the open document, email, note, task, or webpage.

"Get me a hook for whatever's open in Mail"

"Hook the current Obsidian note to this project"

"Link whatever's open in Finder to my TODO"

"Grab a hook URL from Safari and connect it to the design doc"

Supported apps include Finder, Mail, Safari, Obsidian, Bear, DEVONthink, Xcode, and any app that Hookmark supports (most document-based macOS apps).

Moving and Reorganizing Files

When you move or rename a file, its hooks don't follow automatically. Clone them to the new location.

"I moved report.md to the archive — clone its hooks to the new path"

"Copy all links from the old config to the new config file"

"This file replaced the other one — transfer its hooks"

The original keeps its links. The destination gets copies of all the same connections.

Cleaning Up

Remove links you no longer need.

"Unlink the budget spreadsheet from the old project plan"

"Remove the hook between these two files"

"Disconnect the meeting notes from the wrong project"

Real-World Workflows

Research and reference management

"Link this paper PDF to the notes I'm writing about it" "What sources are connected to my literature review?" "Hook this Stack Overflow answer to the bug fix commit"

Project organization

"Connect every file in this project to the project brief" "What's linked to the project requirements? Show me the full list." "Link the Jira ticket URL to the implementation file"

Email and communication

"Hook whatever's open in Mail to this contract PDF" "Search hookmark for that email about the deadline" "Link the client's email to the proposal document"

Code and documentation

"Link the API spec to the implementation in src/api/routes.ts" "What documentation is connected to this module?" "Hook the test file to the source file it tests"

Knowledge management

"Connect this Obsidian note to the original article URL" "What notes are linked to this topic?" "Link the DEVONthink document to my project TODO"

Combining MCP Servers

Hookmark becomes especially powerful when combined with other MCP servers. Here's a workflow that bridges email, document management, and task tracking across devices.

Email → DEVONthink → Hookmark → Todoist

You archive important emails in DEVONthink. DEVONthink items have stable URLs (x-devonthink-item://...) that work in DEVONthink To Go on iOS/iPadOS too. By creating a Hookmark link to a DEVONthink document and adding it to a Todoist task, you get a clickable reference from your task list straight to the email — on any device.

"Search DEVONthink for the email from the lawyer about the contract" "Get a hook URL for that DEVONthink document" "Create a Todoist task 'Review lawyer contract' with that link in the description"

Or in one shot:

"Find the email from Müller about the invoice in DEVONthink, get a hookmark link, and create a Todoist task to follow up on it by Friday"

This works because:

1. DEVONthink MCP finds the archived email

2. Hookmark MCP creates a stable hook:// URL that resolves to the DEVONthink item

3. Todoist MCP creates the task with the link in the description

4. On your iPhone, tapping the link in Todoist opens DEVONthink To Go and jumps straight to the email

The same pattern works with any combination — link Obsidian notes to Todoist tasks, connect GitHub issues to DEVONthink research, hook Calendar events to project files.

MCP Tool Reference

hookmark_link

Get the stable hook:// URL for a file or web URL.

hookmark_connect

Create a bidirectional link between two items.

hookmark_list

List all items hooked to a given item. Omit item to list all bookmarks.

hookmark_search

Search bookmarks by keyword.

hookmark_remove

Remove the bidirectional link between two items.

hookmark_clone

Copy all hooks from source to destination. Source is not modified.

hookmark_frontmost

Get the hook:// URL for the active document in a macOS app.

Configuration

Override the CLI path if your hook binary is installed elsewhere:

Item References

Hookmark items can be referenced in three ways:

• Absolute file path: /Users/you/Documents/report.pdf

• URL: https://example.com/page

• Hook URL: hook://file/5g29VkHoQ?p=...&n=index%2Ets

Hook URLs are stable identifiers — they survive file renames and moves (as long as Hookmark is tracking the file).

Troubleshooting

"hook: command not found" The hook CLI isn't in the expected path. Install it with gem install hookmark or set HOOK_CLI to point to your binary. Find it with which hook or gem which hookmark.

"Hookmark is not running" The hook CLI requires Hookmark.app to be running. Open it from Applications.

Tool calls return empty results Hookmark only knows about items it has bookmarked. Open a file in Hookmark first (or use hookmark_link to create a bookmark), then hooks can be created.

"Permission denied" errors Claude Code needs accessibility permissions to interact with Hookmark via AppleScript. Check System Settings > Privacy & Security > Accessibility.

Requirements

• macOS (Hookmark is macOS-only)

• Hookmark with an active license

• hook CLI v2.0+ (gem install hookmark)

• Node.js 18+ or Bun

License

MIT

Author

Matthias Nott — github.com/mnott