MCP Tools for Obsidian

Features | Installation | Configuration | Troubleshooting | Security | Development | Support

MCP Tools for Obsidian enables AI applications like Claude Desktop to securely interact with your Obsidian vault using the Model Context Protocol (MCP). This plugin comprises an Obsidian plugin and a local MCP server, facilitating secure communication with AI applications. The server acts as a secure bridge, allowing AI assistants to read notes, execute templates, and perform semantic searches without direct access to vault files.

Features

• Vault Access: Securely allows AI assistants to read and reference your notes.
• Semantic Search: Enables AI assistants to search your vault based on meaning and context.
• Template Integration: Executes Obsidian templates through AI interactions.

All features require an MCP-compatible client like Claude Desktop.

Prerequisites

Required

• Obsidian v1.7.7 or higher
• Claude Desktop installed and configured
• Local REST API plugin installed and configured with an API key

Recommended

• Templater plugin for enhanced template functionality
• Smart Connections plugin for semantic search capabilities

Installation

1. Install the plugin from Obsidian's Community Plugins
2. Enable the plugin in Obsidian settings
3. Open the plugin settings
4. Click "Install Server" to download and configure the MCP server

Installation Locations

• Server Binary: {vault}/.obsidian/plugins/obsidian-mcp-tools/bin/
• Log Files:
  • macOS: ~/Library/Logs/obsidian-mcp-tools
  • Windows: %APPDATA%\obsidian-mcp-tools\logs
  • Linux: ~/.local/share/obsidian-mcp-tools/logs

Configuration

The plugin automates the configuration process, requiring explicit permission to install the server binary and modify the Claude Desktop configuration.

Troubleshooting

If you encounter issues:

1. Check the plugin settings to verify:
   • All required plugins are installed
   • The server is properly installed
   • Claude Desktop is configured
2. Review the logs:
   • Open plugin settings
   • Click "Open Logs" under Resources
   • Look for any error messages or warnings

Security

Binary Distribution

• All releases are built using GitHub Actions with reproducible builds
• Binaries are signed and attested using SLSA provenance
• Release workflows are fully auditable in the repository

Runtime Security

• The MCP server runs with minimal required permissions
• All communication is encrypted
• API keys are stored securely using platform-specific credential storage

Binary Verification

The MCP server binaries are published with SLSA Provenance attestations, which provide cryptographic proof of where and how the binaries were built.

Reporting Security Issues

Please report security vulnerabilities via our security policy.
Do not report security vulnerabilities in public issues.

Development

This project uses a monorepo structure with feature-based architecture. For detailed project architecture documentation, see .clinerules.

Workspace

This project uses a Bun workspace structure:

packages/
⌘”œ⌘”€⌘”€ mcp-server/        # Server implementation
⌘”œ⌘”€⌘”€ obsidian-plugin/   # Obsidian plugin
⌘””⌘”€⌘”€ shared/           # Shared utilities and types

Building

1. Install dependencies:

   bun install

2. Build all packages:

   bun run build

3. For development:

   bun run dev

Requirements

• bun v1.1.42 or higher
• TypeScript 5.0+

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests:

   bun test

5. Submit a pull request

Please see CONTRIBUTING.md for detailed guidelines.

Support

• Open an issue for bug reports and feature requests
• Start a discussion for questions and general help

Changelog

See CHANGELOG.md for a list of changes in each release.

License

MIT License

Footnotes

[^1]: For information about Claude data privacy and security, see Claude AI's data usage policy
[^2]: For more information about the Model Context Protocol, see MCP Introduction
[^3]: For a list of available MCP Clients, see MCP Example Clients
[^4]: Requires Obsidian plugin Local REST API
[^5]: Requires Obsidian plugin Smart Connections
[^6]: Requires Obsidian plugin Templater