obsidian-mcp-server

townofnolan/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 dayong@mcphub.com.

The Obsidian MCP Server is a custom Model Context Protocol server designed for seamless integration with Obsidian vaults, enabling advanced note management and AI workflow capabilities.

Tools
4
Resources
0
Prompts
0

Obsidian MCP Server

A custom Model Context Protocol (MCP) server for Obsidian vault integration. Enables Claude Code (desktop & mobile) to read, write, search, and manage your Obsidian notes with support for future AI workflows and external integrations.

Features

  • 🔍 Core Tools: Read, write, search, and list notes
  • 🔄 Git-Backed Sync: Automatic version control and multi-device sync
  • 📱 Mobile Support: Works with Claude Code on iPhone/Android
  • 🔐 Secure Auth: OAuth 2.1 and API key support
  • 🔌 Extensible: Drop-in tool system for adding AI workflows and integrations
  • 🐳 Docker Ready: Easy deployment to any VPS

📊 Current Status

✅ Completed:

  • Obsidian vault created and Git-backed (obsidian-vault)
  • MCP server built and tested locally
  • Environment configuration working
  • Bug fix: Added dotenv package for proper .env loading
  • Server running successfully on localhost:3000

🚧 Next Steps:

  • Docker Compose setup for multi-project VPS deployment
  • Deploy to Hetzner CPX31 (8GB RAM) VPS
  • Configure for remote access (mobile + desktop)

👉 See for detailed deployment plan and VPS setup instructions.

Quick Start

Prerequisites

  • Node.js 20+
  • Git
  • Obsidian vault in a Git repository

Installation

# Clone the repository
git clone https://github.com/yourusername/obsidian-mcp-server.git
cd obsidian-mcp-server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Run in development mode
npm run dev

# Or build and run in production
npm run build
npm start

Configuration

Create a .env file based on .env.example:

GIT_REPO_URL=https://github.com/yourusername/your-vault.git
GIT_BRANCH=main
GIT_TOKEN=ghp_your_token_here
API_KEY=your_secure_api_key

Available Tools

Core Tools

  • read_note - Read note content and frontmatter
  • write_note - Create or update notes
  • search_notes - Full-text search across vault
  • list_notes - List files with optional filtering

Future Extensions (Add as needed)

  • AI workflows (summarization, tagging, templates)
  • Calendar integrations
  • Task management integrations
  • Custom automations

Deployment

Docker (Recommended)

docker build -t obsidian-mcp .
docker run -p 3000:3000 --env-file .env obsidian-mcp

Hetzner VPS

See docs/deployment.md for detailed deployment instructions.

Extending the Server

To add new tools, create a new file in src/tools/:

import { BaseTool } from './base.tool.js';

export class MyCustomTool extends BaseTool {
  name = 'my_custom_tool';
  description = 'Does something custom';

  inputSchema = {
    type: 'object',
    properties: {
      param: { type: 'string' }
    }
  };

  async execute(params: { param: string }) {
    // Your custom logic here
    const content = await this.vault.read(params.param);
    return { success: true, content };
  }
}

The tool will be automatically discovered and registered.

License

MIT

Contributing

This is a personal project, but suggestions and improvements are welcome!