Hookova MCP server: setup guide
Your save library, as tools an assistant can call. Install it once and “save this page,” “what did I save about sourdough,” “tag those three as Recipes” and “summarise everything I saved this week” all become things you can just say. It takes about two minutes and needs no account beyond the one you already have.
What it is
MCP — the Model Context Protocol — is the standard way an AI client asks an outside system to do something. An MCP server is a small program that advertises a set of tools; the client reads that list and calls them when a conversation needs them. The Hookova server advertises six, all of them pointed at your save library.
Two consequences worth knowing before you install it. First, it is local: nothing is hosted, there is no Hookova process watching your conversations, and the only thing that leaves your machine is the API call a tool makes. Second, it is your account: one token, one library, no sharing — and saves made here count against the same daily allowance as everywhere else.
It works with any client that speaks MCP over stdio. The instructions below cover Claude Code, the Claude desktop app and Cursor; anything else follows the same shape.
The six tools
You never call these by name — you ask for what you want and the client picks. They are listed here so you know what it’s allowed to do, which is the useful thing to know about any tool you hand an assistant.
Saves any public URL — a TikTok, Reel or Short, or an ordinary web page.
Returns immediately with status queued; the title, synopsis, takeaways and category are written by a background worker a few seconds later. Saving the same URL twice returns the existing save rather than a duplicate.
Browses and searches the library, newest first.
q searches title, synopsis, URL, notes and tags; tag filters to one category. Also returns every tag with a count and the day's remaining save allowance. Page with the returned nextCursor.
One save in full: synopsis, excerpt, takeaways, tags, notes.
Also reports whether a shot-by-shot analysis exists for the same URL. Read this before update_save, because tags are written as a whole list.
Edits the fields you own on a save.
tags REPLACES the whole list — send the existing tags plus your addition, or the rest are deleted. Everything else on a save is the worker's and can't be set here.
Removes a save and its stored images.
Permanent. There is no undo and no trash to recover it from.
The library in bulk, newest first, with notes and takeaways.
For summarising or reorganising across many saves at once. Capped at 100 by default because the full export runs to thousands of rows — use list_saves to search instead.
update_savereplaces the tag list wholesale. If you ask for “add Recipes to that one,” a good client reads the save first and sends the old tags back with the new one — but it’s worth saying “keep the existing tags” out loud the first few times.Set it up in three steps
You need Bun installed — the server is a TypeScript file run directly, with no build step. Everything else is copy-paste.
Get a token
Two things work, because the server tries both signing salts. Which one you need depends on how you sign in.
If your account has a password
curl -s https://www.hookova.com/api/auth/token \
-H 'content-type: application/json' \
-d '{"email":"you@example.com","password":"…"}' | jq -r .tokenIf you sign in with Google
Those accounts have no password, so there is nothing to mint with — copy the session cookie instead. Sign in at hookova.com, open DevTools → Application → Cookies, and copy the value of __Secure-authjs.session-token. If the browser split it into .0, .1and so on, concatenate the values in order with nothing between them. It’s the same trick the Chrome extension plays.
Either way the token lasts 30 days. Step 3 shows how to make renewal automatic.
Unzip and install
Unzip it somewhere you intend to keep — your client will run the file from wherever it lands, so the Downloads folder is a bad choice.
unzip ~/Downloads/hookova-mcp.zip -d ~/hookova-mcp
cd ~/hookova-mcp
bun installbun install fetches two dependencies: the MCP SDK and zod. Four files go in, nothing is compiled, and nothing is left running.
Register it
In Claude Code, one command does it. Use an absolute path — the client may not expand ~.
claude mcp add hookova \
--env HOOKOVA_TOKEN=eyJ… \
-- bun /Users/you/hookova-mcp/index.tsIf your account has a password, add it here instead of re-pasting a token every month — the server re-mints once on a 401, so expiry becomes invisible:
claude mcp add hookova \
--env HOOKOVA_TOKEN=eyJ… \
--env HOOKOVA_EMAIL=you@example.com \
--env HOOKOVA_PASSWORD=… \
-- bun /Users/you/hookova-mcp/index.tsRestart the client, then check it took: /mcpin Claude Code lists the server and its six tools. Or just ask — “what have I saved lately?” should come back with your library rather than an apology.
Other MCP clients
Every other client wants the same three facts in JSON: the command, its arguments, and the environment. Put this in claude_desktop_config.json (Claude desktop app) or .cursor/mcp.json (Cursor), and the same block works in most editor integrations.
{
"mcpServers": {
"hookova": {
"command": "bun",
"args": ["/Users/you/hookova-mcp/index.ts"],
"env": { "HOOKOVA_TOKEN": "eyJ…" }
}
}
}If the client is a desktop app, give command an absolute path too — e.g. /opt/homebrew/bin/bun. A GUI application doesn’t inherit your shell’s PATH, which is the single most common reason a server registers fine and then shows no tools.
Environment variables
| Variable | What it does | |
|---|---|---|
| HOOKOVA_TOKEN | Required | A minted bearer token or your site session cookie — the server accepts either. Both expire after 30 days. |
| HOOKOVA_EMAIL + HOOKOVA_PASSWORD | Optional | Re-mints a token once on a 401, so expiry is invisible instead of a monthly re-paste. Does nothing on a Google-linked account, which has no password to mint with. |
| HOOKOVA_API | Optional | Defaults to https://www.hookova.com. Point it at http://localhost:3000 to work against a dev server. |
Troubleshooting
Every tool answers “Sign in to save.”
HOOKOVA_TOKEN is missing, misspelled or expired. Mint a fresh one and re-register. If you pasted a session cookie that DevTools had split into __Secure-authjs.session-token.0, .1 and so on, they must be concatenated in order with nothing between them.
The client starts but lists no tools.
The command couldn't run. Check that bun is on the PATH the client uses (a GUI app doesn't inherit your shell's PATH — give the absolute path to bun, e.g. /opt/homebrew/bin/bun) and that the path to index.ts is absolute, not ~-relative, in JSON configs.
Cannot find package '@modelcontextprotocol/sdk'
bun install wasn't run in the unzipped folder, or was run somewhere else. cd into the folder that holds index.ts and run it there.
A save comes back with no title or synopsis.
That's expected — save_link returns as soon as the row exists. The worker fills in the rest a few seconds later; call get_save again to read it.
“Daily save limit reached.”
The allowance is per account and shared with the phone and the browser extension — there's no separate MCP quota. It resets daily.
What it can’t do
Stated plainly, because a tool list that overpromises wastes more of your time than one that’s short.
- No separate quota. Saves made here draw on the same daily allowance as the phone and the extension. There is no MCP tier to raise.
- Local only. Stdio, one process, one token, one account. A hosted server with OAuth is a different piece of work and nobody has asked for it yet.
- No images or video.Keyframes and source videos are auth-gated URLs a model can’t open, so
get_savedrops them rather than handing back links that 401. - Bulk export has a floor.
export_savesreads the Obsidian export route, which returns one page of at most 2,000 rows with no cursor. Past that, the oldest saves aren’t reachable through this tool — uselist_saveswith a search instead. - No analysis. Shot-by-shot video breakdowns stay in the web app;
get_savewill tell you when one already exists for a saved URL.
Frequently asked questions
Does saving through MCP spend an analysis credit?
No. Credits are spent by shot-by-shot video analysis only. Saves count against your daily save allowance, which is shared with the iOS app and the Chrome extension — there is no separate MCP quota.
Do I need the Hookova source repository?
No. The zip is the whole server: one TypeScript file, a package.json, a tsconfig and a README. It calls the public API over HTTPS like any other client.
Where does my data go?
Nowhere new. The server is a local process on your machine that holds one token and talks to the same api.hookova.com routes the iOS app has used since it shipped. Your assistant sees what the tools return, and nothing else.
My account signs in with Google. Can I still use it?
Yes, with the session-cookie route. Google-linked accounts have no password, so there is nothing to mint a token with — copy the session cookie instead. It expires after 30 days, and re-pasting it is the renewal.
Which clients does it work with?
Anything that speaks MCP over stdio: Claude Code, the Claude desktop app, Cursor, and most editor integrations. It is a local stdio server with one token and one account — there is no hosted, OAuth version of it.
Can it analyze a video, not just save it?
Not yet. The six tools cover the save library. Shot-by-shot analysis stays in the web app, and get_save will tell you whether an analysis already exists for a URL you've saved.
Grab the zip, paste the three commands, and the next thing you read worth keeping can be saved without leaving the conversation you’re in.