An Obsidian plugin that exposes your vault operations via the Model Context Protocol (MCP) over HTTP. This allows AI assistants and other MCP clients to interact with your Obsidian vault programmatically.

Features

HTTP MCP Server: Runs an HTTP server implementing the MCP protocol
Vault Operations: Exposes tools for reading, creating, updating, and deleting notes
Search Functionality: Search notes by content or filename
Security: Localhost-only binding, optional authentication, CORS configuration
Easy Configuration: Simple settings UI with server status and controls

Available MCP Tools

Note Operations

read_note - Read the content of a note with optional frontmatter parsing
create_note - Create a new note with conflict handling strategies
update_note - Update an existing note (full content replacement)
delete_note - Delete a note (soft delete to .trash or permanent)
update_frontmatter - Update frontmatter fields without modifying note content
update_sections - Update specific sections of a note by line range
rename_file - Rename or move a file with automatic wikilink updates
read_excalidraw - Read Excalidraw drawing files with metadata extraction (currently limited to uncompressed format; compressed format support is planned)

Vault Operations

search - Search vault with advanced filtering, regex support, and snippet extraction
search_waypoints - Find all Waypoint plugin markers in the vault
list - List files and/or directories with advanced filtering and pagination
stat - Get detailed metadata for a file or folder
exists - Check if a file or folder exists at a specific path
get_vault_info - Get vault metadata (name, path, file counts, total size)

Waypoint Integration

get_folder_waypoint - Get Waypoint block from a folder note
is_folder_note - Check if a note is a folder note

Link Management

validate_wikilinks - Validate all wikilinks in a note and report unresolved links
resolve_wikilink - Resolve a single wikilink from a source note to its target path
backlinks - Get all backlinks to a note with optional unlinked mentions

Installation

From Source

Clone this repository into your vault's plugins folder:

cd /path/to/vault/.obsidian/plugins
git clone <repository-url> obsidian-mcp-server
cd obsidian-mcp-server

Install dependencies:
```
npm install
```
Build the plugin:
```
npm run build
```
Enable the plugin in Obsidian Settings → Community Plugins

Configuration

Open Obsidian Settings → MCP Server
Configure the following options:
- Port: HTTP server port (default: 3000)
- Auto-start: Automatically start server on Obsidian launch
- Enable CORS: Allow cross-origin requests
- Allowed Origins: Comma-separated list of allowed origins
- Enable Authentication: Require API key for requests
- API Key: Bearer token for authentication
Click "Start Server" or use the ribbon icon to toggle the server

Usage

Starting the Server

Via Ribbon Icon: Click the server icon in the left sidebar
Via Command Palette: Run "Start MCP Server"
Auto-start: Enable in settings to start automatically

Connecting an MCP Client

The server exposes an MCP endpoint at:

http://127.0.0.1:3000/mcp

Example client configuration (e.g., for Claude Desktop):

{
  "mcpServers": {
    "obsidian": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Using with Authentication

If authentication is enabled, include the API key in requests:

curl -X POST http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Example MCP Requests

Initialize Connection

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

List Available Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Read a Note

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "read_note",
    "arguments": {
      "path": "folder/note.md"
    }
  }
}

Create a Note

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "create_note",
    "arguments": {
      "path": "new-note.md",
      "content": "# New Note\n\nThis is the content."
    }
  }
}

Search Notes

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "search term"
    }
  }
}

Security Considerations

Localhost Only: The server binds to 127.0.0.1 to prevent external access
Origin Validation: Validates request origins to prevent DNS rebinding attacks
Optional Authentication: Use API keys to restrict access
Desktop Only: This plugin only works on desktop (not mobile) due to HTTP server requirements

Development

Building from Source

npm install
npm run dev    # Watch mode for development
npm run build  # Production build

Make changes to main.ts (or create new .ts files). Those changes should be automatically compiled into main.js.
Reload Obsidian to load the new version of your plugin.
Enable plugin in settings window.
For updates to the Obsidian API run npm update in the command line under your repo folder.

Releasing new releases

Update your manifest.json with your new version number, such as 1.0.1, and the minimum Obsidian version required for your latest release.
Update your versions.json file with "new-plugin-version": "minimum-obsidian-version" so older versions of Obsidian can download an older version of your plugin that's compatible.
Create new GitHub release using your new version number as the "Tag version". Use the exact version number, don't include a prefix v. See here for an example: https://github.com/obsidianmd/obsidian-sample-plugin/releases
Upload the files manifest.json, main.js, styles.css as binary attachments. Note: The manifest.json file must be in two places, first the root path of your repository and also in the release.
Publish the release.

You can simplify the version bump process by running npm version patch, npm version minor or npm version major after updating minAppVersion manually in manifest.json. The command will bump version in manifest.json and package.json, and add the entry for the new version to versions.json

Adding your plugin to the community plugin list

Check the plugin guidelines.
Publish an initial version.
Make sure you have a README.md file in the root of your repo.
Make a pull request at https://github.com/obsidianmd/obsidian-releases to add your plugin.

How to use

Clone this repo.
Make sure your NodeJS is at least v16 (node --version).
npm i or yarn to install dependencies.
npm run dev to start compilation in watch mode.

Manually installing the plugin

Copy over main.js, styles.css, manifest.json to your vault VaultFolder/.obsidian/plugins/your-plugin-id/.

Improve code quality with eslint (optional)

ESLint is a tool that analyzes your code to quickly find problems. You can run ESLint against your plugin to find common bugs and ways to improve your code.
To use eslint with this project, make sure to install eslint from terminal:
- npm install -g eslint
To use eslint to analyze this project use this command:
- eslint main.ts
- eslint will then create a report with suggestions for code improvement by file and line number.
If your source code is in a folder, such as src, you can use eslint with this command to analyze all files in that folder:
- eslint ./src/

Funding URL

You can include funding URLs where people who use your plugin can financially support it.

The simple way is to set the fundingUrl field to your link in your manifest.json file:

{
    "fundingUrl": "https://buymeacoffee.com"
}

If you have multiple URLs, you can also do:

{
    "fundingUrl": {
        "Buy Me a Coffee": "https://buymeacoffee.com",
        "GitHub Sponsor": "https://github.com/sponsors",
        "Patreon": "https://www.patreon.com/"
    }
}

API Documentation

See https://github.com/obsidianmd/obsidian-api