Obsidian Knowledge

You run a local MCP server that exposes Obsidian vault data through a stateless API, enabling AI tools to read, analyze, and manage Markdown files, frontmatter, and wikilinks in your vault with safe, atomic operations.

How to use

Interact with the server through an MCP client to read notes, search content, and inspect vault structure. You will operate the server in stdio mode on your machine, then point your client at the local process. The server exposes navigation tools like listing notes, reading notes with metadata, batch reading, full‑text search, and vault structure queries. Each call returns precise metadata such as paths, headings, links, and statistics to support editor assistants and LLM workflows.

Typical usage pattern:

How to install

Prerequisites you need before installing: Node.js (with npm) is required to run the MCP server locally.

# Install dependencies
npm install

# Build the project
npm run build

# Optional: run in development/watch mode
npm run dev

Configuration and operation

The server runs against a vault path you specify. You provide the vault location via an environment variable when starting the server or through a .env file.

Starting the server with a vault path set in the environment enables the MCP to access your Obsidian vault securely and without caching. You should validate that the vault path is correct and accessible by the process.

Security and stability

Path validation prevents directory traversal attacks by ensuring all file operations stay under the configured vault root. The server is stateless, performing pure data access and atomic operations, so there is no semantic analysis happening on the server side.

If a file cannot be found or is inaccessible, you receive a structured error with a clear code and actionable guidance to recover.

Notes on environment and commands

The server is designed to be launched with a command similar to the following, where you point to your vault and the built JavaScript entry file.

VAULT_PATH="./Test Vault" node dist/index.js

Troubleshooting

If you encounter path validation errors, double-check that VAULT_PATH points to a real directory and that your vault does not attempt to traverse above the vault root.

If a note cannot be read, ensure the file exists at the vault-relative path and that the process has read permissions.

Notes for integration with Claude Desktop

To connect Claude Desktop, configure the MCP entry with the appropriate command and environment variables, then reference the absolute path to the built MCP entry.

{
  "mcpServers": {
    "obsidian_knowledge": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-knowledge-mcp/dist/index.js"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Available tools (Phase 1 - Navigation)

The MCP server exposes a set of navigation tools to work with your vault content.

1. list_notes — List all notes with optional filtering including folder, tags, dateRange, offset, and limit.

2. read_note — Read a single note with full metadata, including content, frontmatter, outgoing links, headings, and stats.

3. read_notes_batch — Read multiple notes in one call, returning the same structure as read_note for each path.

4. search_notes — Full‑text search across the vault with optional regex support, folder narrowing, and limit on occurrences.

5. get_vault_structure — Get the folder hierarchy with note counts.

Development

Key architectural pieces separate the MCP server, tool handlers, and vault/parser logic. You can run in development mode to watch changes, run unit tests, or perform integration testing with a test vault.

Build, test, and lint commands help maintain code quality and ensure your server remains reliable for local AI workflows.

Available tools

list_notes

List all notes with optional filters: folder, tags, dateRange, offset, and limit.

read_note

Read a single note with full metadata including content, frontmatter, outgoing links, headings, and stats.

read_notes_batch

Read multiple notes in one call, returning the same structure as read_note for each path.

search_notes

Perform a full-text search across the vault with optional regex, folder restriction, and per-note limit.

get_vault_structure

Return the folder hierarchy with note counts for the vault.