Registry / productivity / obsidian-mcp-server

obsidian-mcp-server

library3.2.4jsnpmunverified

An MCP-compliant server that provides tools for reading, writing, searching, and editing notes, tags, and frontmatter in Obsidian vaults. Version 3.2.4 requires Node >=24 or Bun >=1.3.11 and the Obsidian Local REST API plugin. Uses stdio or Streamable HTTP transport. Built in TypeScript with full type definitions. Differentiates from generic file-sys MCP servers by offering high-level operations (get note content, list vault files, append to notes, bulk create, search by content/tag, manage tags/frontmatter, batch delete) with a two-edit safety guard. The server enforces contextual editing to avoid data loss. Release cadence is active (multiple updates per month). Ships with a React-based MCP inspector for testing.

productivity

npm install obsidian-mcp-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OBSIDIAN-MCP-SERVE

obsidian-mcp-server

productivityjavascriptv3.2.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Server (class)

✓ import { Server } from 'obsidian-mcp-server'

✗ const Server = require('obsidian-mcp-server').Server

Package exports a default export (the ObsidianMCPServer class) and named exports. ESM-only since v3.0; CommonJS require() will not work on Node >=24 without appropriate flags.

runStdioServer

✓ import { runStdioServer } from 'obsidian-mcp-server'

✗ import ObsidianMCPServer from 'obsidian-mcp-server'

The default export is the ObsidianMCPServer class. The function `runStdioServer` is a named export that creates and runs a server via stdin/stdout. If you use the default import, you must instantiate the class manually.

TransportType enum

✓ import { TransportType } from 'obsidian-mcp-server'

Available transports: TransportType.STDIO and TransportType.STREAMABLE_HTTP. Introduced in v3.0. If you are on an older version (<3.0), use Server class options directly.

Shows how to start the server over stdio transport, configure API URL and key, and set max note size. Replace the API key with a real one from the Local REST API plugin settings.

import { runStdioServer } from 'obsidian-mcp-server'; // The server reads required config from environment variables: // OBSIDIAN_API_URL (default: http://127.0.0.1:27124) // OBSIDIAN_API_KEY (the API key from the Local REST API plugin) const apiKey = process.env.OBSIDIAN_API_KEY ?? 'your-api-key'; const apiUrl = process.env.OBSIDIAN_API_URL ?? 'http://127.0.0.1:27124'; async function main() { const server = await runStdioServer({ apiUrl, apiKey, maxNoteSize: 1000000, // 1 MB limit for note content }); console.log('Obsidian MCP server running on stdio'); // The server runs until process exit } main().catch(console.error);

Debug

Known issues

breakingRequires Node >= 24 or Bun >= 1.3.11. Older runtimes will fail to start.

fix

Upgrade Node to 24+ or use Bun 1.3.11+.

affects: >=3.0.0

breakingThe package is ESM-only from v3.0.0. CommonJS require() will not work.

fix

Use dynamic import() or switch to ESM ("type": "module" in package.json).

affects: >=3.0.0

gotchaObsidian vault must have the Local REST API plugin installed and configured. The API key must match the one set in the plugin.

fix

Install 'obsidian-local-rest-api' from Obsidian community plugins; set an API key in its settings; pass same key to server.

affects: >=1.0.0

gotchaEdits are guarded: a note can only be edited twice (two edits per note). Then you must re-read the note to continue editing. This prevents stale data overwrites.

fix

Design your workflow to call 'get_note' after every two edits, or use the 'two_edit_guard' option (if available) to disable it.

affects: >=3.0.0

deprecatedStreamable HTTP transport is deprecated in favor of stdio in v3.2.0? Actual advice: stdio is recommended due to simpler setup.

fix

Use stdio transport (TransportType.STDIO) when possible.

affects: >=3.2.0

Errors

Common errors & fixes

Error: ERR_REQUIRE_ESM: require() of ES Module [path] from [path] not supported.

Using CommonJS require() with an ESM-only package (v3+).

fix

Use dynamic import() or set "type": "module" in package.json and use import syntax.

Error: fetch failed: connect ECONNREFUSED 127.0.0.1:27124

Obsidian Local REST API plugin is not running or the port is incorrect.

fix

Start Obsidian and ensure the Local REST API plugin is enabled. Verify the port (default 27124) and URL.

Error: 401 Unauthorized: invalid API key

OBSIDIAN_API_KEY is missing or does not match the key set in the Local REST API plugin.

fix

Set OBSIDIAN_API_KEY environment variable to the exact API key from Obsidian plugin settings.

Upgrade

Version history

3.2.4latest on npm

Audit

Dependencies

obsidian-local-rest-apirequiredrequired plugin in Obsidian; the server communicates with it

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cyanheads/obsidian-mcp-server ↗

packageobsidian-mcp-server ↗

homepagehttps://github.com/cyanheads/obsidian-mcp-server#readme ↗