A Friday vault digest
Prompt
Every Friday at 16:00, list the notes in my Obsidian vault changed in the last seven days, write one line on what each change was about, and append the list to a note called Weekly Digest.md.
Verified MCP server: Obsidian
The Obsidian MCP server, started and enumerated live on a real Mac.
- Tools enumerated2026-08-03macOS 26.3.1
- Packagemcp-obsidian 0.2.2
- Self-reportedmcp-obsidian 1.29.0
- MCP protocol2025-06-18
- RuntimePython 3.11.13 (uvx)
The tool list below is a live capture from the running server; an authenticated tool call is still pending credentials.
The short answer
Last verified 2026-08-03
The Obsidian MCP server connects an AI assistant to your vault through the Obsidian Local REST API community plugin, not by reading the vault folder on disk. It is a Python package you start with uvx, it needs that plugin switched on inside Obsidian and the API key the plugin issues, and the requests it makes go to 127.0.0.1 on the plugin's own port. We ran it: the server started, the MCP handshake completed, and it listed all 12 tools, printed below word for word. We did not have the plugin running, so the two tool calls we made came back with real connection errors rather than any notes of ours, and the first of those errors is printed too. Everything that still needs your own key is labelled as such on this page. [1][3][6][7]
Verification
How this MCP server was verified.
Method
We spawned the server with uvx over stdio, using the absolute path that which uvx reports, with a placeholder API key and the MCP Python SDK pinned below version 2. The initialize handshake completed, tools/list returned the 12 tools printed below word for word, and we then made two real tools/call requests. Authenticated calls are still pending a credential we do not have: the API key issued by the Obsidian Local REST API community plugin, which also has to be installed and running inside Obsidian. Both calls answered with a connection refusal, and the first of them is the sample result shown here, captured on the wire. Two notes on the receipts above: this server prints no banner of its own, so the two banner lines are the MCP SDK request log it wrote while answering us, and the 1.29.0 it reports as its version is that SDK version rather than the package version 0.2.2, because the server passes the SDK no version string of its own. Nothing on this page claims an authenticated call succeeded.
Startup banner
INFO:mcp.server.lowlevel.server:Processing request of type ListToolsRequest INFO:mcp.server.lowlevel.server:Processing request of type CallToolRequest
One real tool call
tools/call obsidian_list_files_in_vault {}Caught Exception. Error: Request failed: HTTPSConnectionPool(host='127.0.0.1', port=27124): Max retries exceeded with url: /vault/ (Caused by NewConnectionError("HTTPSConnection(host='127.0.0.1', port=27124): Failed to establish a new connection: [Errno 61] Connection refused"))Real lines from the captured result: enough to prove the call answered.
Tools
Every tool, enumerated from the running server.
The server answered tools/list with 12 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| obsidian_list_files_in_dirdirpath* | Lists all files and directories that exist in a specific Obsidian directory. |
| obsidian_list_files_in_vault | Lists all files and directories in the root directory of your Obsidian vault. |
| obsidian_get_file_contentsfilepath* | Return the content of a single file in your vault. |
| obsidian_simple_searchquery*context_length | Simple search for documents matching a specified text query across all files in the vault. Use this tool when you want to do a simple text search |
| obsidian_patch_contentfilepath*operation*target_type*target*content* | Insert content into an existing note relative to a heading, block reference, or frontmatter field. |
| obsidian_append_contentfilepath*content* | Append content to a new or existing file in the vault. |
| obsidian_delete_filefilepath*confirm* | Delete a file or directory from the vault. |
| obsidian_complex_searchquery* | Complex search for documents using a JsonLogic query. Supports standard JsonLogic operators plus 'glob' and 'regexp' for pattern matching. Results must be non-falsy. Use this tool when you want to do a complex search, e.g. for all documents with certain tags etc. |
| obsidian_batch_get_file_contentsfilepaths* | Return the contents of multiple files in your vault, concatenated with headers. |
| obsidian_get_periodic_noteperiod* | Get current periodic note for the specified period. |
| obsidian_get_recent_periodic_notesperiod*limitinclude_content | Get most recent periodic notes for the specified period type. |
| obsidian_get_recent_changeslimitdays | Get recently modified files in the vault. |
Parameters marked with * are required.
Setup
Working configs, one per app.
Copy the block for the app you use. Each one is the configuration this server was verified with.
Claude Desktop
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"mcp-obsidian": {
"command": "uvx",
"args": [
"--with",
"mcp<2",
"mcp-obsidian"
],
"env": {
"OBSIDIAN_API_KEY": "your-plugin-api-key",
"OBSIDIAN_HOST": "127.0.0.1"
}
}
}
}Paste the API key from Obsidian, Settings, Local REST API. If Claude Desktop cannot find uvx, run which uvx in Terminal once and use that full path as the command. Then quit and reopen Claude Desktop. [5][7]
Claude Code
One command in your terminal:
claude mcp add obsidian -e OBSIDIAN_API_KEY=your-plugin-api-key -e OBSIDIAN_HOST=127.0.0.1 -- uvx --with 'mcp<2' mcp-obsidian
The server name comes first, before the -e flags: each -e keeps taking arguments until the next flag, so a name written after them is read as another variable and the command fails. Everything after the double dash is the exact command Claude Code will run. Keep the quotes around mcp<2: unquoted, your shell reads the less-than sign as a redirect. [11]
Cursor
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"mcp-obsidian": {
"command": "uvx",
"args": [
"--with",
"mcp<2",
"mcp-obsidian"
],
"env": {
"OBSIDIAN_API_KEY": "your-plugin-api-key",
"OBSIDIAN_HOST": "127.0.0.1"
}
}
}
}Cursor picks the file up on restart. If it cannot find uvx, run which uvx in Terminal once and use that full path as the command. [12]
Routines
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name Obsidian Command uvx Arguments --with mcp<2 mcp-obsidian Environment Variables OBSIDIAN_API_KEY your-plugin-api-key
Environment Variables is a pair of boxes, not one line: OBSIDIAN_API_KEY goes in the name box and your key in the value box next to it. The Arguments field splits on spaces, and none of these three arguments contains one. If Routines cannot find uvx, run which uvx in Terminal once and paste that full path as the Command, because an app opened from Finder does not inherit the PATH your terminal uses. Click Test Connection first: a working server answers with its tool count, twelve for this one, even before Obsidian is running. [13]
No terminal needed
Set the Obsidian MCP server up without the terminal.
If you have never opened Terminal and never want to, this is your path. Routines is a Mac app that runs MCP servers for you: fill in a few fields once, and this server's tools are available to your AI in chat and in scheduled routines. The one thing you cannot skip is the Obsidian plugin, because that is what actually opens your vault.
01
Install Routines
Download the app from getroutines.ai/download, drag it to Applications, and sign in.
02
Turn on the Obsidian plugin and copy its key
In Obsidian: Settings, then Community plugins, then Browse, and install Local REST API by coddingtonbear. Enable it, then open Settings, Local REST API and copy the API key it shows. Leave Obsidian running: the server talks to this plugin, so a closed Obsidian means no vault.
03
Open the MCP settings
Back in Routines, click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
04
Choose Command (stdio) and fill it in
Switch the form to Command (stdio): this server is a command, not a web address. Name: Obsidian. Command: uvx. Arguments: --with mcp<2 mcp-obsidian. In Environment Variables add OBSIDIAN_API_KEY with the key you copied from the plugin.
05
Test, then add
Click Test Connection: Routines starts the server and reports how many tools it found, twelve for this one. That number proves the server runs; it does not prove your key is right, which you find out on the first real question. Then click Add Server.
06
Use it
The tools work in chat right away: ask for a note by name to confirm the key works. To let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Routines worth scheduling.
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
A morning carry-over list
Prompt
Every weekday at 8:00, read my Obsidian daily note for yesterday, find anything still unfinished, and append it to today's daily note under a heading called Carried over.
A monthly reading round-up
Prompt
On the first Monday of each month at 10:00, search my Obsidian vault for notes mentioning books I finished, summarise them in a short paragraph each, and append the summary to Reading Log.md.
Troubleshooting
The errors we hit, and what fixed them.
Real errors captured during the verification run, printed exactly as the server returned them.
The server crashes on start if you leave the SDK unpinned
What you see
@app.list_tools()
^^^^^^^^^^^^^^
AttributeError: 'Server' object has no attribute 'list_tools'The fix
This is what plain uvx mcp-obsidian does today, and it is why every config on this page carries the pin. The published package asks for mcp version 1.1.0 or newer, and version 2.0.0 of the MCP Python SDK, released on 2026-07-28, removed that decorator. Adding --with mcp<2 in front of the package name holds the SDK at 1.x, and the server then starts and lists all twelve tools, which is the run this page is built from.
The server exits immediately and your client says it failed to start
What you see
raise ValueError(f"OBSIDIAN_API_KEY environment variable required. Working directory: {os.getcwd()}")
ValueError: OBSIDIAN_API_KEY environment variable required. Working directory: /private/tmpThe fix
The API key is read at import time, so with no key the process dies before it can speak MCP at all. Put OBSIDIAN_API_KEY in the env block of your client config, or in the Environment Variables field in Routines, with the key from Obsidian, Settings, Local REST API.
Every tool answers with a connection error
What you see
Caught Exception. Error: Request failed: HTTPSConnectionPool(host='127.0.0.1', port=27124): Max retries exceeded with url: /vault/ (Caused by NewConnectionError("HTTPSConnection(host='127.0.0.1', port=27124): Failed to establish a new connection: [Errno 61] Connection refused"))The fix
Nothing is listening on the plugin port. This is the error we captured, because the Local REST API plugin was not installed on our test Mac. Check three things in order: Obsidian is open, the Local REST API plugin is enabled, and the port in its settings is the one in your config, 27124 by default. The server itself is fine: it started and listed its tools with the same placeholder key.
Your MCP client cannot start the server at all
The fix
The uvx command belongs to uv, the Python package runner. If uv is not installed on your Mac, every client on this page fails at the spawn step before the server can say anything. Install uv from docs.astral.sh/uv, then run which uvx and paste that full path as the command if your client still cannot find it.
FAQ
Questions people ask.
What is the Obsidian MCP server?
It is a small Python program that lets an AI assistant such as Claude read, search, append to, and delete notes in your Obsidian vault. It does not open your vault folder itself: it makes HTTP requests to the Obsidian Local REST API community plugin running inside Obsidian, so Obsidian has to be open and that plugin enabled. It runs as a local process on your Mac and talks to your AI app over stdio. [5][6][7]
What did you actually verify, and what still needs my key?
We verified that the server starts, completes the MCP handshake, and enumerates its tools: the table above is that live tools/list output, word for word. We used a placeholder API key and did not have the plugin installed, so the two real tool calls we made both returned a connection error, and the first of them is printed above as the sample result. Reading and writing your actual notes needs your own plugin key and a running Obsidian, and we make no claim about that beyond what the tools describe.
What tools does the Obsidian MCP server include?
The running server exposes 12 tools: browsing (obsidian_list_files_in_vault, obsidian_list_files_in_dir), reading (obsidian_get_file_contents, obsidian_batch_get_file_contents), search (obsidian_simple_search, obsidian_complex_search), writing (obsidian_append_content, obsidian_patch_content, obsidian_delete_file), periodic notes (obsidian_get_periodic_note, obsidian_get_recent_periodic_notes), and recent activity (obsidian_get_recent_changes). The table above is the live output, word for word.
Do I need the Obsidian Local REST API plugin?
Yes, for this package. It is a free community plugin by coddingtonbear that you install from inside Obsidian, and it hands you the API key this server needs. Worth knowing before you install anything else: the plugin now ships an MCP server of its own at https://127.0.0.1:27124/mcp/, so a client that speaks HTTP MCP, such as Claude Code, can connect to the plugin directly and skip this package. [7]
Why do the configs pin the MCP SDK below version 2?
Because without the pin the package does not start. The last release on PyPI is 0.2.2 from 2025-04-01 and it accepts any MCP Python SDK from 1.1.0 up. Version 2.0.0 of that SDK landed on 2026-07-28 and removed the decorator this server uses, so a plain uvx mcp-obsidian now dies with an AttributeError, which we captured and printed in the troubleshooting section. Adding --with mcp<2 holds the SDK at 1.x and the server runs. [1][8]
Is there a version that just reads my vault folder?
There are several, and they need no plugin and no key because they open the markdown files directly: you pass the vault path as an argument instead. One of them is obsidian-mcp on npm, at about 3.6k downloads a week against roughly 9.7k for this package, though npm and PyPI do not count downloads the same way. We built this page around the plugin-based one because those numbers point to it as the more used of the two, and because a server that goes through Obsidian sees your live vault, including notes still open in the editor. [9][10][2]
Which apps can use the Obsidian MCP server?
Any MCP client that can launch a local stdio server: Claude Desktop, Claude Code, Cursor, and Routines all can, and the exact config for each is above. The server itself is the same in every client; only the place you paste the config differs, and every one of them needs the same API key in its environment block. [11][12][13]
Sources
Every external claim, receipted.
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
PyPI JSON API: mcp-obsidianaccessed 2026-08-03Latest version 0.2.2, published 2025-04-01; it requires mcp>=1.1.0 and Python 3.11 or newer.
[2]
PyPI download stats: mcp-obsidianaccessed 2026-08-039,728 downloads in the last week and 36,559 in the last month.
[3]
GitHub: MarkusPfundstein/mcp-obsidianaccessed 2026-08-034,248 stars and a push dated 2026-05-15 at access time, per the GitHub API.
[4]
[5]
mcp-obsidian READMEaccessed 2026-08-03The uvx config shape, the plugin requirement, and the defaults: host 127.0.0.1, port 27124.
[6]
mcp-obsidian source: server.pyaccessed 2026-08-03Runs the MCP Server inside stdio_server(): the server speaks stdio.
[7]
GitHub: coddingtonbear/obsidian-local-rest-apiaccessed 2026-08-032,736 stars, MIT, pushed 2026-08-03 at access time. Its README documents the API key location, the 27124 HTTPS port, and the plugin's own MCP endpoint.
[8]
PyPI JSON API: mcp, the Python SDKaccessed 2026-08-03Version 2.0.0 published 2026-07-28; 1.29.0, the version our run resolved, was published the same day.
[9]
npm registry: obsidian-mcpaccessed 2026-08-03The folder-reading alternative: version 1.0.6, MIT, and 3,555 downloads for the week ending 2026-08-01 per the npm downloads API.
[10]
GitHub: StevenStavrakis/obsidian-mcpaccessed 2026-08-03Its README config passes vault paths straight to the command, so it needs no plugin and no key.
[11]
Claude Code docs: MCPaccessed 2026-08-03The claude mcp add syntax for local stdio servers, including the -e/--env flag for environment variables.
[12]
[13]
Routines: Connectorsaccessed 2026-08-03How Routines runs one-click OAuth connectors and any MCP server.
This page describes Obsidian as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. Your notes stay markdown files on your Mac, there is no cloud bill, and it works offline. Download Routines