Obsidan MCP TS Server

You run an Obsidian MCP server written in TypeScript that lets you interact with Obsidian through a local REST API and expose powerful resource and editing tools to MCP clients. It provides fast, cache-friendly access to vault data, safe editing operations, and a growing set of tools for reading, searching, and modifying your notes with strong type safety and clear error handling.

How to use

You connect an MCP client to the Obsidian MCP server to read vault data, perform searches, and edit notes. Start the server locally and point your client at the server through a standard MCP connection. You can use both resources and tools to read data and perform actions inside Obsidian.”},{

How to install

Prerequisites: you need Node.js and npm installed on your machine. You also need Obsidian with the Local REST API plugin enabled and an API key generated for the Obsidian REST API.

# 1) Install the MCP server globally
npm install -g obsidian-mcp-ts

# 2) Ensure Obsidian REST API plugin is installed and API key is available
# The API key can be provided via environment or a config file

# 3) Start the server using the recommended runtime (either development or published flow)

Starting the server can be done via two common approaches shown in configuration examples. Use the development flow for local testing or the published flow for a quick start with your environment set up.

{
  "mcpServers": {
    "obsidian-mcp-dev": {
      "command": "node",
      "args": ["<path_to>/obsidian-mcp-ts/dist/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "<YOUR_OBSIDIAN_API_KEY>"
      }
    },
    "obsidian-mcp-pub": {
      "command": "npx",
      "args": ["obsidian-mcp-ts"],
      "env": {
        "OBSIDIAN_API_KEY": "<YOUR_OBSIDIAN_API_KEY>"
      }
    }
  }
}

Additional setup notes

If you prefer a persistent configuration, you can place your API key and host in a config file and reference it from your MCP client configuration. You can also run via Claude Desktop by configuring an MCP server entry that points to the local MCP server and passes the API key in the environment.

Configuration and security

Security: store your API key in a secure place and avoid committing it to version control. Use a dedicated config file for persistent setups and restrict file permissions (for example, 600 on config files). If you share access to the machine running the MCP server, rotate keys regularly.

Troubleshooting and notes

If you encounter authentication issues, verify that OBSIDIAN_API_KEY is correctly set in your environment or config file. If a resource or tool call fails with a not-found error, first verify the vault path and the availability of the Obsidian REST API plugin.

Performance improvements come from internal resource caching with automatic invalidation when files change. If you notice stale data, ensure the Obsidian vault is actively updated through the editing tools and that the cache durations align with your workflow.

Tools usage overview

The server exposes a range of tools to interact with your vault. These tools offer file operations, directory management, advanced searches, and structured edits. You can use them to read content, modify notes, and build complex workflows with confidence.

Available tools

obsidian_list_files_in_vault

List all files and directories in the root of your Obsidian vault.

obsidian_list_files_in_dir

List contents of a specific directory in the vault; empty directories return an empty array.

obsidian_find_empty_directories

Find all empty directories within the vault by scanning the structure.

obsidian_get_file_contents

Return the full content of a single file in the vault.

obsidian_batch_get_file_contents

Return the contents of multiple files, concatenated with headers for readability.

obsidian_simple_search

Perform a simple text search across all vault documents.

obsidian_advanced_search

Execute a structured search with filters for content and metadata.

obsidian_complex_search

Use complex JsonLogic-based queries where supported by the API.

obsidian_edit

Unified editing tool with progressive complexity for modifying vault notes.

obsidian_simple_append

Append text to a file with automatic newline handling.

obsidian_simple_replace

Find and replace text within a file.

obsidian_query_structure

Query the document structure to identify headings and blocks before edits.

obsidian_append_content

Append content to a new or existing file in the vault.

obsidian_delete_file

Delete a file or directory from the vault.

obsidian_rename_file

Rename a file within the same directory while preserving history and updating links.

obsidian_move_file

Move a file to a different location while preserving history and links.

obsidian_move_directory

Move an entire directory and its contents to a new location.

obsidian_copy_file

Copy a file to a new location, preserving content.

obsidian_copy_directory

Copy an entire directory and its contents to a new location.

obsidian_check_path_exists

Check if a file or directory exists and determine its type.

obsidian_create_directory

Create a new directory with support for nested paths.

obsidian_delete_directory

Delete a directory and its contents, with optional recursive deletion.

obsidian_get_all_tags

List all unique tags in the vault with usage counts.

obsidian_get_files_by_tag

Get all files that contain a specific tag.

obsidian_rename_tag

Rename a tag across the entire vault.

obsidian_manage_file_tags

Add or remove tags on a specific file, optimized for batch operations.

obsidian_get_periodic_note

Get the current periodic note for a given period (daily, weekly, etc.).

obsidian_get_recent_periodic_notes

Get the most recent periodic notes for the specified period type.

obsidian_get_recent_changes

Get recently modified files with optional previews.

obsidian_get_file_metadata

Fetch file metadata such as size and dates without loading content.

obsidian_get_file_frontmatter

Retrieve only the frontmatter for a file.

obsidian_get_file_formatted

Return a file in different formats (plain text, HTML) for token optimization.