Obsidian MCP Plugin

Integrates the Model Context Protocol (MCP) with Obsidian, providing a self-contained server that enables AI assistants to interact with your vault. This plugin uses standardized tools and resources for seamless AI collaboration.

Key Features and Benefits

This plugin offers a native and streamlined Model Context Protocol (MCP) experience directly within Obsidian, with its own built-in server - no external dependencies required.

• Self-Contained Server: Built-in HTTP/HTTPS server with no external dependencies
• Native Obsidian Integration: Operates as a standard Obsidian plugin for a seamless user experience
• Flexible Connectivity: Supports both SSE and Streamable HTTP transports for versatile communication
• HTTPS Support: Automatic self-signed certificate generation for secure connections
• Optional Certificate Import: Can import existing certificates from Obsidian Local REST API plugin for seamless migration
• User-Friendly Configuration: Manage all settings through the standard Obsidian interface
• Comprehensive Toolset:
  • Complete MCP server functionality
  • Tools for file management (read, list, metadata), vault search, and querying
  • Resource-based access to vault files and daily notes
  • Built-in prompt management system
• Plugin Integrations:
  • Dataview: Execute Dataview queries (requires Dataview plugin)
  • Daily Notes: Interact with daily notes (requires Daily Notes or Periodic Notes plugin)
  • QuickAdd: Trigger QuickAdd actions and list choices (requires QuickAdd plugin)
  • TaskNotes: Query and manage tasks with filtering by status, priority, and context (requires TaskNotes plugin)

Installation

This plugin is not yet in the Obsidian Community Plugins directory. Install it via BRAT (Beta Reviewers Auto-update Tester):

1. Install BRAT from Obsidian Community Plugins.
2. In BRAT settings, add beta plugin: rygwdn/obsidian-mcp-plugin.
3. Enable the plugin in Obsidian settings.
4. Create an authentication token in the Authentication section of the plugin settings. Choose the appropriate permissions (Read for queries, Write for modifications).
5. The plugin will automatically start its server once you create your first token. Your Obsidian vault will now provide an MCP endpoint at http://127.0.0.1:27125/mcp (HTTP) or https://127.0.0.1:27126/mcp (HTTPS). By default, the server uses HTTP on port 27125.
6. Copy the generated token and use it in your MCP client configuration as a Bearer token.

Migration from Local REST API

If you were previously using this plugin with the Obsidian Local REST API plugin:

1. The MCP plugin now runs its own server - you no longer need Local REST API for MCP functionality
2. Your existing certificate can be imported via the "Import Certificate from Local REST API" button in Server Configuration settings
3. Important: Create at least one authentication token, as authentication is now required
4. All other settings will be preserved during the migration

Authentication

All requests to the MCP server require Bearer token authentication. The plugin uses a token-based system with granular permissions:

Token Permissions

• Read: Allows querying vault content, searching, and reading files
• Write: Allows modifying content, creating files, and executing actions

Using Tokens

Include your token in the Authorization header:

{
 "type": "streamableHttp",
 "url": "http://127.0.0.1:27125/mcp",
 "headers": {
  "Authorization": "Bearer YOUR_TOKEN_HERE"
 }
}

Note: The server defaults to HTTP (not HTTPS). You can enable HTTPS in the Server Configuration settings if needed.

Managing Tokens

1. Navigate to plugin settings → Authentication section
2. Click "Create New Token"
3. Give it a descriptive name and select permissions
4. Copy the token immediately (you won't see it again!)
5. Store it securely in your MCP client configuration

Security Notes:

• Tokens are randomly generated using cryptographically secure methods
• Each token can have different permissions
• You can create multiple tokens for different clients
• Delete unused tokens to maintain security
• Track token usage via the "Last used" timestamp

Available Functionality

This plugin offers a range of functionalities that can be enabled or disabled through the settings:

• File Access: Allows AI assistants to read files, list directories, and retrieve file metadata within your vault. This is fundamental for many interactions that require understanding the content and structure of your notes. Security impact: Exposes vault content to connected systems.

• Content Modification: Grants AI assistants the ability to modify file content. This includes actions like appending text to existing notes, replacing sections of text, or creating new content based on instructions. Security impact: HIGH - enables direct changes to your vault content.

• Vault Search: Enables AI assistants to perform text-based searches across all files in your vault. This is useful for finding specific information or patterns within your notes. Security impact: Makes all content discoverable through search queries.

• Dataview Integration: If you have the Dataview plugin installed and enabled, this feature allows AI assistants to execute Dataview queries. This can be powerful for querying and summarizing structured data within your notes (requires Dataview plugin). Security impact: Can expose aggregated data from your entire vault.

• Daily Notes Integration: Provides specialized tools for interacting with daily notes. This requires either the core Daily Notes plugin or the Periodic Notes plugin (configured for daily notes) to be active. It simplifies tasks like creating, retrieving, or updating daily entries.

• QuickAdd Integration: If you use the QuickAdd plugin, this feature allows AI assistants to trigger QuickAdd actions and list available choices. This can automate workflows and content creation processes defined in QuickAdd (requires QuickAdd plugin). Security impact: HIGH - QuickAdd actions can modify vault content, run scripts, or interact with external services, depending on how they are configured.

• TaskNotes Integration: If you use the TaskNotes plugin, this feature allows AI assistants to query tasks across your vault with powerful filtering options. You can filter by status (incomplete, completed, cancelled), priority (high, medium, low, none), and context tags. The integration also provides task statistics and the ability to look up individual tasks by file path (requires TaskNotes plugin). Security impact: Exposes task data from your vault to connected systems.

• Logging Verbosity: Controls console logging detail level. By default, logging is minimal, but you can enable "Verbose Logging" in Advanced settings for debugging.

Each of these features can be toggled in the plugin's settings, allowing you to customize the level of access and capability granted to connected AI assistants.

[!CAUTION] Content modification permissions allow AI assistants to make direct changes to your vault files. Enable this permission only when needed and review any changes carefully.

For comprehensive information on security, permissions, and privacy considerations, please review the SECURITY.md document.

Using Prompts

The plugin features a simple prompt management system:

1. Create a Markdown file in your prompts folder (default: prompts/).
2. Define Metadata (Optional): Add YAML frontmatter to the top of the file. The following fields are supported:
   • name: (string) A human-readable name for the prompt.
   • description: (string) A brief description of what the prompt does.
   • args: (array of strings) A list of variable names that your prompt will use.
3. Write your prompt in the file body, using {{variable1}} for placeholders.

Prompts are automatically registered and updated with the MCP server. AI assistants can access them.

Example Prompt (prompts/analyze_topic.md):

---
name: "Topic Analysis"
description: "Create an analysis of a topic"
args:
  - "topic"
  - "perspective"
---

Please provide a thorough analysis of {{topic}} from a {{perspective}} perspective. Include
historical context, current relevance, and future implications.

Development

Key commands:

• npm run dev: Development with hot reload.
• npm run build: Build for production.
• npm run check: Type check, lint, and test.
• npm run install:link -- /path/to/your/vault: Install to vault for testing (symlinks).

Release Process

1. Update CHANGELOG.md (e.g., ## [x.y.z] - YYYY-MM-DD).
2. Bump version: npm run version.
3. Tag and push: git tag x.y.z && git push origin x.y.z.

GitHub Actions will draft a release from the changelog.

Related Projects

• mcp-obsidian: External MCP server for Obsidian.
• obsidian-mcp: Filesystem-based MCP server.
• Model Context Protocol: Official MCP documentation.

License

MIT