Obsidian MCP Server

# 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](https://github.com/townofnolan/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 [NEXT-STEPS.md](NEXT-STEPS.md) for detailed deployment plan and VPS setup instructions.** ## Quick Start ### Prerequisites - Node.js 20+ - Git - Obsidian vault in a Git repository ### Installation ```bash # 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`: ```env 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) ```bash 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/`: ```typescript 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!