obsidian-mcp-server

robwilde/obsidian-mcp-server

3.2

If you are the rightful owner of obsidian-mcp-server 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.

The Obsidian MCP Server for Claude Code enables seamless integration between Claude Code and Obsidian, allowing AI-generated content to be saved directly to an Obsidian vault with proper formatting and organization.

Tools
4
Resources
0
Prompts
0

Obsidian MCP Server for Claude Code

šŸ¤– Seamlessly save Claude Code responses directly to your Obsidian vault with automatic formatting and project-specific organization.

Overview

This MCP (Model Context Protocol) server creates a bridge between Claude Code and Obsidian, allowing you to automatically save AI-generated content (reports, code reviews, documentation) directly to your Obsidian vault with proper formatting and organization.

āœØ Key Features

  • šŸŽÆ Direct Integration: Ask Claude Code to "save to Obsidian" and it happens automatically
  • šŸ“ Project-Specific Organization: Configure custom folders and templates per project
  • šŸŽØ Rich Formatting: Automatic frontmatter, timestamps, and structured templates
  • āš™ļø Easy Setup: One-command installation with interactive configuration
  • šŸ”§ Flexible Templates: Customizable templates for reports, reviews, and notes
  • šŸ”— Obsidian URL Support: Read files directly from Obsidian URLs with space/special character handling

Quick Start

1. Installation

Clone this repository and run the interactive installer:

git clone https://github.com/robwilde/obsidian-mcp-server.git
cd obsidian-mcp-server
python3 install.py

The installer will:

  • āœ… Check Python 3.8+ and install MCP dependencies
  • āœ… Prompt for your Obsidian vault path
  • āœ… Install the MCP server globally to ~/.claude/
  • āœ… Configure Claude Code settings automatically
  • āœ… Optionally create project-specific configuration

2. Usage

After installation, simply ask Claude Code:

"Create a security review of the authentication system and save to Obsidian"
"Generate API documentation and save it to Obsidian as a report"
"Document the database schema and save to Obsidian"
"Read this Obsidian file: obsidian://open?vault=MyVault&file=Notes/ProjectPlan"
"@obsidian obsidian://open?vault=MyVault&file=Docs%2FMeeting%20Notes%202025"

Claude Code will automatically use the appropriate tools to interact with your Obsidian vault.

Project Configuration

Global Setup

The MCP server is installed globally and configured via ~/.claude/settings.json:

{
  "mcpServers": {
    "obsidian-claude-code": {
      "command": "python3",
      "args": ["/home/user/.claude/obsidian_mcp_server.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Project-Specific Configuration

Each project can have custom settings in .claude/obsidian.json:

{
  "folder": "Projects/My Awesome Project",
  "templates": {
    "report": "# {title}\n\n**šŸ“‹ Report Generated**\n- **Date:** {timestamp}\n- **Project:** {project}\n\n{content}",
    "review": "# Code Review: {title}\n\n**šŸ‘€ Review Details**\n- **Date:** {timestamp}\n- **Project:** {project}\n\n{content}",
    "note": "# {title}\n\n**šŸ“ Note**\n- **Created:** {timestamp}\n- **Project:** {project}\n\n{content}"
  }
}

Adding Project Config to Existing Projects

python3 install.py --project-config

File Structure

obsidian-mcp-server/
ā”œā”€ā”€ README.md                              # This file
ā”œā”€ā”€ install.py                             # Interactive installer
ā”œā”€ā”€ obsidian_mcp_server.py                 # Main MCP server
ā”œā”€ā”€ hook.py                                # Claude Code hook script (optional)
ā”œā”€ā”€ CLAUDE.md                              # Development guidance
ā”œā”€ā”€ .claude/obsidian.json                  # Example project config
ā””ā”€ā”€ Building an MCP Server...md            # Detailed implementation guide

How It Works

Architecture

  1. MCP Server: Runs as a background service providing tools to Claude Code
  2. Project Detection: Automatically detects project context and configuration
  3. Template Engine: Formats content using customizable templates
  4. File Organization: Saves files to project-specific folders in your vault

Available Tools

The MCP server provides these tools to Claude Code:

  • save_to_obsidian: Primary tool for saving formatted content with templates
  • read_obsidian_url: Read files from Obsidian URLs (handles URL encoding for spaces and special characters)
  • save_claude_response: Direct response saving (if implemented via hooks)
  • list_vault_files: Browse existing vault files (planned)
  • get_vault_structure: View vault folder hierarchy (planned)

Generated File Format

Files are automatically saved with:

---
created: 2025-01-27T14:30:22.123456
source: claude-code
tags: [claude-code, report, project-name]
---

# Security Review: Authentication System

**šŸ“‹ Report Generated**
- **Date:** 2025-01-27 14:30:22
- **Project:** my-awesome-project
- **Type:** Technical Report

---

[Your content here, formatted according to the template]

---

*Generated by Claude Code*

Requirements

  • Python 3.8+
  • Claude Code (with MCP support)
  • Obsidian (any recent version)
  • MCP Python package (auto-installed by installer)

Advanced Usage

Reading Obsidian URLs

The read_obsidian_url tool allows Claude Code to read files directly from Obsidian URLs:

# Basic usage
"Read file from: obsidian://open?vault=MyVault&file=Notes/ProjectPlan"

# With URL-encoded spaces and special characters
"@obsidian obsidian://open?vault=MyVault&file=Meeting%20Notes%2FQ1%202025"

# Files with special characters in names
"Read: obsidian://open?vault=DevNotes&file=Issues%2FWAI-130%20Assignee%20field"

The tool automatically:

  • Parses the vault name and file path from the URL
  • Handles URL-encoded characters (spaces, slashes, special chars)
  • Adds .md extension if not present
  • Uses the configured OBSIDIAN_VAULT_PATH to locate files

Custom Templates

Modify .claude/obsidian.json to customize how different content types are formatted:

{
  "templates": {
    "security-review": "# šŸ”’ Security Review: {title}\n\n**Reviewed by:** Claude Code\n**Date:** {timestamp}\n\n## Executive Summary\n\n{content}",
    "api-docs": "# šŸ“š API Documentation: {title}\n\n**Generated:** {timestamp}\n**Version:** 1.0\n\n{content}"
  }
}

Environment Variables

  • OBSIDIAN_VAULT_PATH: Path to your Obsidian vault (set by installer)

Debugging

Enable debug logging by setting:

export MCP_DEBUG=1

Troubleshooting

Common Issues

MCP server not found

# Reinstall MCP dependencies
pip install --upgrade mcp

Vault path not found

# Check environment variable
echo $OBSIDIAN_VAULT_PATH

# Or update settings manually
vim ~/.claude/settings.json

Project config not detected

# Create project config in current directory
python3 install.py --project-config

Support

  • Check the file for development guidance
  • Review the detailed implementation guide in the documentation
  • Ensure Claude Code is restarted after installation

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test with the install script
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

Made with ā¤ļø for the Claude Code community