Obsidian MCP Server
An MCP (Model Context Protocol) server for integrating AI assistants with your Obsidian vault. Supports both stdio and HTTP/SSE transports for maximum compatibility.
Features
- Session Reports: Automatically save coding session summaries with metadata
- Note Management: Create, read, append, and search notes
- Daily Notes Integration: Append to daily notes automatically
- TODO Tracking: Create and manage TODOs with priorities and due dates
- Backlink Discovery: Find notes that link to a specific note
- Smart Linking: Get suggestions for related notes based on keywords
- Dual Transport: Supports both stdio (direct) and HTTP/SSE (networked) modes
Quick Start with Docker (Recommended)
The easiest way to run the server is with Docker Compose:
# Clone the repository
git clone https://github.com/igorilic/obsidian-mcp.git
cd obsidian-mcp
# Create your environment file
cp .env.example .env
# Edit .env and set your vault path
# OBSIDIAN_VAULT_HOST_PATH=/path/to/your/obsidian/vault
# Start the server
docker compose up -d
# Verify it's running
curl http://localhost:9111/health
The server will be available at http://localhost:9111/mcp.
Installation (Local)
Prerequisites
- Node.js 18+
- npm or pnpm
Steps
git clone https://github.com/igorilic/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run build
Client Setup
Claude Code (CLI)
Claude Code supports HTTP transport natively. Add to your global config at ~/.claude.json:
{
"mcpServers": {
"obsidian": {
"type": "http",
"url": "http://localhost:9111/mcp"
}
}
}
Or for stdio transport (direct, no Docker):
{
"mcpServers": {
"obsidian": {
"type": "stdio",
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
After adding, restart Claude Code or run /mcp to reconnect.
Claude Desktop
Claude Desktop only supports stdio transport, so use mcp-remote as a bridge for HTTP servers.
Config location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
For HTTP transport (with Docker):
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:9111/mcp"]
}
}
}
For stdio transport (direct, no Docker):
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
Restart Claude Desktop after changes.
Cursor
Cursor supports MCP servers with stdio, SSE, and HTTP transports.
Config location:
- Global:
~/.cursor/mcp.json - Project:
.cursor/mcp.json
For stdio transport:
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
For HTTP transport:
{
"mcpServers": {
"obsidian": {
"url": "http://localhost:9111/mcp",
"transport": "sse"
}
}
}
Or configure via UI: File → Preferences → Cursor Settings → MCP
Documentation: Cursor MCP Docs
Windsurf
Windsurf uses the same config format as Claude Desktop.
Config location: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
Or configure via UI: Windsurf Settings → Cascade → Plugins
Documentation: Windsurf MCP Docs
Zed
Zed has built-in MCP support but currently only supports stdio transport (not HTTP).
Config location: ~/.config/zed/settings.json
{
"context_servers": {
"obsidian": {
"command": {
"path": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
}
To verify: Check the Agent Panel settings - a green indicator means the server is active.
Documentation: Zed MCP Docs
VS Code with Continue
Continue supports MCP servers via YAML configuration files.
Config location: Create .continue/mcpServers/obsidian.yaml in your workspace or home directory:
For stdio transport:
name: Obsidian MCP Server
version: 1.0.0
schema: v1
mcpServers:
- name: obsidian
command: node
args:
- /path/to/obsidian-mcp/dist/index.js
env:
OBSIDIAN_VAULT_PATH: /path/to/your/obsidian/vault
For HTTP transport:
name: Obsidian MCP Server
version: 1.0.0
schema: v1
mcpServers:
- name: obsidian
type: streamable-http
url: http://localhost:9111/mcp
Documentation: Continue MCP Docs
VS Code with Cline
Cline supports both stdio and SSE transports.
Click the MCP Servers icon in Cline's top navigation → Configure → Advanced MCP Settings
For stdio transport:
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
For SSE/HTTP transport:
{
"mcpServers": {
"obsidian": {
"url": "http://localhost:9111/mcp",
"transport": "sse"
}
}
}
Documentation: Cline MCP Docs
JetBrains IDEs (IntelliJ, WebStorm, PyCharm, etc.)
JetBrains AI Assistant supports MCP servers starting from version 2025.1.
Setup via UI:
- Go to Settings → Tools → AI Assistant → Model Context Protocol (MCP)
- Click + to add a new server
- Configure the server
For stdio transport:
{
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
Note: MCP tools only work with "Codebase" mode enabled in the chat window.
Documentation: JetBrains MCP Docs
Generic HTTP Client
For any client supporting HTTP/SSE MCP transport:
- Endpoint:
http://localhost:9111/mcp - Health check:
http://localhost:9111/health - Protocol: MCP over Streamable HTTP (SSE responses)
- Required headers:
Accept: application/json, text/event-stream
Example initialization request:
curl -X POST http://localhost:9111/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {"name": "my-client", "version": "1.0.0"}
}
}'
Transport Modes
HTTP/SSE Transport (Default for Docker)
Best for:
- Multiple clients connecting simultaneously
- Networked/remote access
- Containerized deployments
# Using Docker
docker compose up -d
# Or manually
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node dist/index.js
Stdio Transport (Default for local)
Best for:
- Direct integration with IDEs
- Single client usage
- Lower latency
OBSIDIAN_VAULT_PATH=/path/to/vault node dist/index.js
Available Tools
| Tool | Description |
|---|---|
write_session_report | Save coding session summaries with metadata |
write_note | Create or overwrite a note |
append_to_note | Append content to an existing note |
append_to_daily_note | Append to today's daily note |
search_notes | Search notes by content, tags, or folder |
read_note | Read a note's content and frontmatter |
list_recent_notes | List recently modified notes |
find_backlinks | Find notes linking to a specific note |
create_todo | Create a TODO item |
link_notes | Get suggestions for related notes |
Tool Details
write_session_report
{
title: string; // Short title (required)
summary: string; // Brief summary (required)
details?: string; // Detailed description
files_changed?: string[]; // List of modified files
next_steps?: string[]; // Follow-up TODOs
tags?: string[]; // Tags for categorization
project?: string; // Project name
folder?: string; // Subfolder in Claude-Sessions
}
write_note
{
path: string; // Relative path (required)
content: string; // Markdown content (required)
title?: string; // Note title
tags?: string[]; // Tags
frontmatter?: object; // Additional frontmatter
}
search_notes
{
query: string; // Search query (required)
tags?: string[]; // Filter by tags
folder?: string; // Limit to folder
limit?: number; // Max results (default: 20)
}
create_todo
{
task: string; // Task description (required)
project?: string; // Project tag
priority?: string; // "high" | "medium" | "low"
due_date?: string; // YYYY-MM-DD format
context?: string; // Additional context
todo_file?: string; // Target file (default: "TODOs.md")
}
Environment Variables
| Variable | Description | Default |
|---|---|---|
OBSIDIAN_VAULT_PATH | Path to Obsidian vault | Required |
MCP_TRANSPORT | Transport mode: stdio or http | stdio |
MCP_HTTP_PORT | HTTP server port (when using http transport) | 3000 |
Vault Structure
The server creates/uses this structure:
Your Vault/
├── Claude-Sessions/ # Session reports
│ ├── project-name/ # Per-project folders
│ │ └── 2024-01-15-1430-feature-complete.md
│ └── 2024-01-15-1200-quick-fix.md
├── Daily Notes/ # Daily notes (configurable)
│ └── 2024-01-15.md
└── TODOs.md # TODO items
Development
# Watch mode
npm run dev
# Build
npm run build
# Run with stdio
OBSIDIAN_VAULT_PATH=/path/to/vault npm start
# Run with HTTP
MCP_TRANSPORT=http npm start
# Docker build
docker compose build
# Docker logs
docker compose logs -f
Troubleshooting
"Server not initialized" error
The MCP client has a stale session. Solutions:
- Claude Code: Run
/mcpto reconnect - Claude Desktop: Restart the app
- Docker: Run
docker compose restart
Connection refused
Ensure the server is running:
curl http://localhost:9111/health
Permission denied writing notes
If using Docker, ensure the vault is mounted with write access (:rw not :ro) in your .env file.
MCP tools not appearing
- Check server logs:
docker compose logs - Verify configuration path is correct
- Restart your IDE/client
- For JetBrains: Ensure "Codebase" mode is enabled
Zed shows "Server not active"
Zed doesn't support HTTP transport yet. Use stdio configuration instead.
License
MIT