# obsidian-local-rest-api: a REST API and MCP server for your vault

> The plugin exposes the same vault operations over HTTPS and over the Model Context Protocol, so scripts and AI agents share one interface. The trade-off is a locally generated certificate authority you have to trust or work around.

**coddingtonbear/obsidian-local-rest-api** — A secure REST API and Model Context Protocol (MCP) server for your vault.

- Repository: https://github.com/coddingtonbear/obsidian-local-rest-api
- Website: https://coddingtonbear.github.io/obsidian-local-rest-api/
- Stars: 2,980 · Forks: 349
- Language: TypeScript
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/coddingtonbear-obsidian-local-rest-api

## What the plugin solves, and for whom

Obsidian stores a vault as a folder of Markdown files, but it does not ship an interface for other programs to read and write notes while the app is running. The plugin fills that gap: it runs inside Obsidian and serves an authenticated HTTP interface on the loopback address, so a script, a browser extension, or an AI agent can act on the same vault the user has open. The README frames the audience directly: "Give your scripts, browser extensions, and AI agents a direct line into your Obsidian vault via a secure, authenticated REST API." Two interfaces are exposed, and the README states they expose the same core capabilities, so a tool written against the REST endpoints and an agent speaking MCP are working against one set of operations. The operations listed include full CRUD on any file including binary files, section-level patching, full-text and JsonLogic search, reading or writing the active file, listing and executing Obsidian commands, querying tags, and opening a file in the Obsidian UI. That is a broader surface than a simple file watcher, because command execution and the active-file endpoints require the plugin to be running inside Obsidian rather than reading the folder from outside.

## How the HTTPS listener and the MCP endpoint fit together

The plugin listens on two ports. HTTPS is served on 127.0.0.1:27124 and is the default; a plain HTTP listener on 127.0.0.1:27123 is off until it is enabled under Settings, Local REST API, Enable HTTP server. The MCP server is mounted at /mcp/ on the same host and port, so https://127.0.0.1:27124/mcp/ is the endpoint a client connects to, and it takes the same bearer token in an Authorization header. Authentication is a single API key, found in the plugin settings along with the certificate; the README's first example, a request to the bare root, is the one call that needs no auth. On first run the plugin generates its own certificate authority and serves a server certificate signed by it. That CA is name-constrained, meaning it can only vouch for 127.0.0.1, localhost, the configured binding host, and the hostnames listed under Subject alternative names. The README is explicit about why that matters: trusting it does not let it, or anyone who obtains its key, impersonate other sites. The design keeps the API on the loopback interface and makes the certificate's blast radius small, which is the right shape for a plugin that can execute Obsidian commands and delete arbitrary files.

## Installing the plugin and making a first authenticated call

Installation is through Obsidian's community plugin flow; the README links the Obsidian Community page for the plugin and says to install and enable it, after which Settings, Local REST API shows the API key and certificate. There is no separate server binary to run. The first check needs no credentials, and the -k flag tells curl to accept the self-signed chain:

```bash
curl -k https://127.0.0.1:27124/
```

If the server is up you get a response rather than a connection error. The next call lists the root of the vault and is the first one that needs the key from the settings pane:

```bash
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/
```

To stop passing -k, download the CA and point curl at it. The README notes the download is a CA certificate rather than the server certificate, and that it can be trusted in the OS or browser:

```bash
curl --cacert obsidian-local-rest-api.crt \
  -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md
```

Writing to a section rather than a whole file uses PATCH with a JSON instruction naming the target type, the target, the operation and the content:

```bash
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["My Section"],"operation":"append","content":"New line of content"}' \
  https://127.0.0.1:27124/vault/path/to/note.md
```

The README shows append here; the same instruction shape covers prepend, replace, delete and move, and the target can be a heading, a block reference or a frontmatter key. For an MCP client, the Claude Code CLI is the shortest path, and it takes the token as a header:

```bash
claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \
  --header "Authorization: Bearer <your-api-key>"
```

The README also gives the equivalent .mcp.json entry for Claude Code, a Cursor entry for ~/.cursor/mcp.json or .cursor/mcp.json, and a Claude Desktop configuration that bridges the HTTP endpoint through mcp-remote because Claude Desktop does not natively support remote HTTP MCP servers.

## The certificate is the first thing that will stop you

Almost every failure with this plugin traces back to the local CA. Clients that verify TLS will reject https://127.0.0.1:27124/ until the CA is trusted or passed explicitly, which is why the README offers two exits: download the CA at /obsidian-local-rest-api.crt and trust it, or enable the plain HTTP listener on 127.0.0.1:27123 and point the client there. The HTTP path is easier and weaker, since the API key then travels unencrypted, though only over loopback. A second constraint is transport support on the client side. The README states that any MCP client supporting the Streamable HTTP transport can connect, and that Claude Desktop does not natively support remote HTTP MCP servers, which is why the mcp-remote bridge exists and why Node.js is required for that path. If your client speaks only stdio and you do not want a bridge, this is the wrong tool. A third is the scope of the key itself: it gates every endpoint in the README's table, including command execution and file deletion, and the README does not document scoped tokens or per-endpoint permissions. Treat the key like a shell on the vault, because that is what it is.

## How it differs from the Obsidian Local REST API plugin alternatives

The obvious comparison is running a general-purpose HTTP file server or a sync daemon over the vault folder. Those see files, not Obsidian. They cannot read the currently active note, trigger a command from the command palette, or resolve a block reference the way Obsidian does, because that state lives in the running app. The plugin's PATCH model is the sharpest difference: targeting a heading, block reference or frontmatter key and appending, prepending, replacing, deleting or moving just that section means a caller does not have to read, edit and rewrite an entire file, which is where concurrent writers corrupt notes. The second comparison is against MCP servers that wrap a filesystem. Those give an agent file reads and writes, but not tag queries, not command execution, and not the active-file endpoint. The plugin's extension interface is a third axis: the README documents that other plugins can register their own routes through an API extension interface, with a typed extension API and a list of known extensions, so the surface is not fixed at what ships today. The cost of all this is that the API only exists while Obsidian is running with the plugin enabled. A headless server or a CI job that needs the vault without the app has no path here.

## Maintenance, licence and what upgrading costs

The repository is not archived, and the last push was on 2026-09-21, with release 5.2.0 tagged the same day, 5.1.0 on 2026-08-01 and 5.0.3 on 2026-07-30. That is a recent release cadence, and the version history suggests minor releases arrive on the order of weeks to a couple of months. The licence is MIT, which permits commercial and private use and modification provided the copyright notice and permission notice are included; that is a statement about the licence text, not legal advice, and anyone redistributing the plugin or a derivative should read the LICENSE file at the repository root rather than rely on this summary. For upgrade cost, the practical exposure is that this is an Obsidian community plugin, so updates arrive through the plugin browser in Obsidian and are tied to the app version that loads them. The repository's manifest.json and versions.json are bumped by a version script, which is the mechanism that maps plugin releases to compatible Obsidian versions. The README documents MCP protocol revisions, which is the part most likely to move: a client that pins an older revision may need attention after an upgrade, and the README is the place that records which revisions are supported. The repository requires Node.js 22 or later for development, per the engines field, but that constraint applies to building the plugin, not to using it.

## Conclusion

Adopt it if you need programmatic access to a vault from scripts, browser extensions or an MCP client such as Claude Code or Cursor, and you are willing to handle the certificate. Skip it if you need remote access, a managed cloud service, or a client that only speaks stdio without a bridge such as mcp-remote. Before you rely on it, confirm that your Obsidian version loads the plugin, that your client's transport matches what the README documents, and that your own backup routine covers the vault, because the API can delete any file in it.

## FAQ

### How do I install obsidian-local-rest-api?

It installs as an Obsidian community plugin: the README says to install and enable the plugin, then open Settings, Local REST API to find the API key and certificate. There is no separate server process to start.

### Is there an API for Obsidian?

Obsidian does not ship one, but this plugin adds one: it serves an authenticated REST API and an MCP server on the loopback interface while Obsidian is running. Both interfaces expose the same core capabilities according to the README.

### Does Obsidian only run locally?

The plugin is built around a local Obsidian instance: it binds to 127.0.0.1 on ports 27124 for HTTPS and 27123 for the optional HTTP listener. The README does not describe any remote or hosted deployment.

### What is the purpose of a REST API?

In this project it is the interface that lets scripts, browser extensions and AI agents read, create, update and delete notes in the vault, patch individual sections, search, and trigger Obsidian commands, all over authenticated HTTPS on the loopback address.

## Sources

- [coddingtonbear/obsidian-local-rest-api on GitHub](https://github.com/coddingtonbear/obsidian-local-rest-api)
- [License: MIT](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/LICENSE)
- [Project website](https://coddingtonbear.github.io/obsidian-local-rest-api/)
- [README](https://github.com/coddingtonbear/obsidian-local-rest-api/blob/main/README.md)
- [Releases](https://github.com/coddingtonbear/obsidian-local-rest-api/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/coddingtonbear-obsidian-local-rest-api