obsidian-mcp
If you are the rightful owner of obsidian-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Obsidian MCP (Model Context Protocol) 服务器用于连接 AI 模型与 Obsidian 知识库，支持笔记和文件夹的管理操作。
Obsidian MCP (Model Context Protocol) Server
English |
This project implements a Model Context Protocol (MCP) server for connecting AI models with Obsidian knowledge bases. Through this server, AI models can directly access and manipulate Obsidian notes, including reading, creating, updating, and deleting notes, as well as managing folder structures.
Created by huangyihe
- Prompt House: https://prompthouse.app/
- YouTube: https://www.youtube.com/@huanyihe777
- Twitter: https://x.com/huangyihe
- Community: https://t.zsxq.com/19IaNz5wK
Features
- Seamless integration with Obsidian knowledge bases
- Support for reading, creating, updating, and deleting notes
- Support for creating, renaming, moving, and deleting folders
- Full-text search functionality
- Compliance with the Model Context Protocol specification
Supported Tools
The MCP server provides the following tools:
list_notes: List all notes in the Obsidian vaultread_note: Read the content of a note in the Obsidian vaultcreate_note: Create a new note in the Obsidian vaultsearch_vault: Search for content in the Obsidian vaultdelete_note: Delete a note from the Obsidian vaultmove_note: Move or rename a note to a new location in the Obsidian vaultmanage_folder: Create, rename, move, or delete a folder in the Obsidian vault
Prerequisites
- Node.js (v16 or higher)
- Obsidian desktop application
- Obsidian Local REST API plugin (needs to be installed in Obsidian)
Installation Options
Choose the most suitable installation method based on your technical level and usage needs:
| Method | Target Users | Advantages | Disadvantages |
|---|---|---|---|
| 🎯 One-Click Install (DXT) | General users | Simplest, GUI configuration | Requires DXT-enabled client |
| 📦 Remote Install (NPM) | Node.js users | Auto-updates, no installation | Requires network connection |
| 🔧 Local Deploy | Advanced users | Offline use, full control | Manual updates required |
Method 1: One-Click Install (DXT Package) - Recommended
Suitable for: General users who want the simplest installation experience
Step 1: Download DXT File
Download the pre-built extension package:
Step 2: Install and Configure
Double-click the downloaded .dxt file and the system will automatically install the extension. Then fill in the configuration interface:
- Vault Path: Your Obsidian vault path (e.g.,
/Users/username/Documents/MyVault) - API Token: Obsidian Local REST API plugin token
- API Port: API port number (default:
27123)
Method 2: Remote Install (NPM Package)
Suitable for: Node.js developers who want automatic updates and version management
Simply add the following configuration to your MCP client config file:
Using npx (recommended, no pre-installation required):
{
"mcpServers": {
"obsidian-mcp": {
"command": "npx",
"args": [
"@huangyihe/obsidian-mcp"
],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
"OBSIDIAN_API_TOKEN": "your_api_token",
"OBSIDIAN_API_PORT": "27123"
}
}
}
}
Note: First run will automatically download the package, subsequent runs use cache, ensuring you always use the latest version.
Method 3: Local Deploy
Suitable for: Users who need customization, advanced control, or offline usage
Option A: Global Install (Recommended)
Step 1: Global Install
npm install -g @huangyihe/obsidian-mcp
Step 2: MCP Client Configuration
{
"mcpServers": {
"obsidian-mcp": {
"command": "obsidian-mcp",
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
"OBSIDIAN_API_TOKEN": "your_api_token",
"OBSIDIAN_API_PORT": "27123"
}
}
}
}
Option B: Source Deploy
Step 1: Clone Repository
git clone https://github.com/newtype-01/obsidian-mcp.git
cd obsidian-mcp
Step 2: Install Dependencies
npm install
Step 3: Build Project
npm run build
Step 4: Configure Environment Variables
cp .env.example .env
# Edit .env file with your configuration
Step 5: Start Server
npm start
Option C: Docker Deploy
Using Docker Compose (Recommended)
# Configure environment variables
cp .env.example .env
# Edit .env file
# Start service
docker-compose up -d
Using Docker Command
# Build image
docker build -t obsidian-mcp .
# Run container
docker run -d \
--name obsidian-mcp \
--env-file .env \
--network host \
-v $(OBSIDIAN_VAULT_PATH):$(OBSIDIAN_VAULT_PATH) \
obsidian-mcp
Configuration Guide
Environment Variables
All installation methods require the following configuration:
OBSIDIAN_VAULT_PATH: Path to your Obsidian vaultOBSIDIAN_API_TOKEN: API token for Obsidian Local REST API pluginOBSIDIAN_API_PORT: API port for Obsidian Local REST API (default: 27123)
⚠️ Important: For remote NPM installation and global installation, you MUST use the OBSIDIAN_ prefix for environment variables. The variables VAULT_PATH, API_TOKEN without the prefix will not work correctly.
Getting API Token
- Install "Local REST API" plugin in Obsidian
- Generate API Token in plugin settings
- Note the port number (default 27123)
Testing
The project includes a test script to verify server functionality:
node test-mcp.js
Development
- Use
npm run devto run the server in development mode - Source code is located in the
srcdirectory
License
MIT
Contributing
Pull Requests and Issues are welcome!
