# 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!