# 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:
```bash
# 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
```bash
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`:
```json
{
"mcpServers": {
"obsidian": {
"type": "http",
"url": "http://localhost:9111/mcp"
}
}
}
```
Or for stdio transport (direct, no Docker):
```json
{
"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):**
```json
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:9111/mcp"]
}
}
}
```
**For stdio transport (direct, no Docker):**
```json
{
"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:**
```json
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
```
**For HTTP transport:**
```json
{
"mcpServers": {
"obsidian": {
"url": "http://localhost:9111/mcp",
"transport": "sse"
}
}
}
```
Or configure via UI: **File → Preferences → Cursor Settings → MCP**
Documentation: [Cursor MCP Docs](https://docs.cursor.com/context/model-context-protocol)
---
### Windsurf
Windsurf uses the same config format as Claude Desktop.
**Config location:** `~/.codeium/windsurf/mcp_config.json`
```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](https://docs.windsurf.com/windsurf/cascade/mcp)
---
### Zed
Zed has built-in MCP support but currently only supports stdio transport (not HTTP).
**Config location:** `~/.config/zed/settings.json`
```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](https://zed.dev/docs/ai/mcp)
---
### VS Code with Continue
[Continue](https://continue.dev/) supports MCP servers via YAML configuration files.
**Config location:** Create `.continue/mcpServers/obsidian.yaml` in your workspace or home directory:
**For stdio transport:**
```yaml
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:**
```yaml
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](https://docs.continue.dev/customize/deep-dives/mcp)
---
### VS Code with Cline
[Cline](https://github.com/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:**
```json
{
"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:**
```json
{
"mcpServers": {
"obsidian": {
"url": "http://localhost:9111/mcp",
"transport": "sse"
}
}
}
```
Documentation: [Cline MCP Docs](https://docs.cline.bot/mcp/configuring-mcp-servers)
---
### JetBrains IDEs (IntelliJ, WebStorm, PyCharm, etc.)
JetBrains AI Assistant supports MCP servers starting from version 2025.1.
**Setup via UI:**
1. Go to **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**
2. Click **+** to add a new server
3. Configure the server
**For stdio transport:**
```json
{
"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](https://www.jetbrains.com/help/ai-assistant/mcp.html)
---
### 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:
```bash
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
```bash
# 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
```bash
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
<details>
<summary><code>write_session_report</code></summary>
```typescript
{
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
}
```
</details>
<details>
<summary><code>write_note</code></summary>
```typescript
{
path: string; // Relative path (required)
content: string; // Markdown content (required)
title?: string; // Note title
tags?: string[]; // Tags
frontmatter?: object; // Additional frontmatter
}
```
</details>
<details>
<summary><code>search_notes</code></summary>
```typescript
{
query: string; // Search query (required)
tags?: string[]; // Filter by tags
folder?: string; // Limit to folder
limit?: number; // Max results (default: 20)
}
```
</details>
<details>
<summary><code>create_todo</code></summary>
```typescript
{
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")
}
```
</details>
---
## 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
```bash
# 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 `/mcp` to reconnect
- **Claude Desktop**: Restart the app
- **Docker**: Run `docker compose restart`
### Connection refused
Ensure the server is running:
```bash
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
1. Check server logs: `docker compose logs`
2. Verify configuration path is correct
3. Restart your IDE/client
4. 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
