obsidian-mcp/README.md

# Obsidian MCP Server

A lightweight, high-performance Model Context Protocol (MCP) server for Obsidian vaults written in Go.

## Features

- **Full Obsidian Support**: Read, create, update, and delete notes with frontmatter, wikilinks, and tags
- **Git Integration**: Automatic version control with commit, pull, and push operations
- **Fast Search**: Full-text search, tag-based search, and frontmatter filtering
- **Graph Navigation**: Backlinks, outlinks, and graph traversal
- **45+ MCP Tools**: Comprehensive API for note management and vault operations
- **High Performance**: < 100ms read operations, supports vaults with 10,000+ notes
- **Clean Architecture**: Domain-driven design with clear separation of concerns

## Installation

### Binary Release
```bash
# Download the latest release for your platform
curl -L https://github.com/user/obsidian-mcp-server/releases/latest/download/obsidian-mcp-linux -o obsidian-mcp
chmod +x obsidian-mcp
```

### Go Install
```bash
go install github.com/user/obsidian-mcp-server/cmd/obsidian-mcp@latest
```

### Docker
```bash
docker run -v /path/to/vault:/vault ghcr.io/user/obsidian-mcp-server:latest
```

## Quick Start

1. **Configure MCP Client** (Claude Desktop example):
```json
{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp",
      "args": ["--vault", "/path/to/your/vault"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

2. **Start the server**:
```bash
obsidian-mcp --vault /path/to/your/vault
```

3. **Use with Claude**: The server will be available through the MCP protocol with 45+ tools for note management.

## Configuration

### Environment Variables
```bash
export VAULT_PATH=/path/to/vault          # Required: Path to Obsidian vault
export LOG_LEVEL=info                     # Optional: debug, info, warn, error
export GIT_ENABLED=true                   # Optional: Enable git operations
export GIT_AUTO_PUSH=false                # Optional: Auto-push changes
export CACHE_ENABLED=true                 # Optional: Enable caching
```

### Config File (config.yaml)
```yaml
server:
  name: obsidian-mcp
  transport: stdio

vault:
  path: /path/to/vault
  exclude_paths:
    - .obsidian/
    - .git/
    - .trash/

git:
  enabled: true
  auto_pull: true
  auto_push: false
  auto_commit: true

logging:
  level: info
  format: text
```

## MCP Tools

The server provides 45+ MCP tools organized into categories:

### File Operations (5)
- `read_note` - Read note with metadata
- `create_note` - Create new note
- `update_note` - Update existing note
- `delete_note` - Delete note
- `rename_note` - Rename note and update links

### Search Operations (3)
- `search_content` - Full-text search
- `search_by_tags` - Search by tags
- `search_by_frontmatter` - Search by frontmatter

### Link Operations (5)
- `get_backlinks` - Get notes linking to this note
- `get_outlinks` - Get notes this note links to
- `get_graph` - Get graph neighborhood
- `find_broken_links` - Find broken wikilinks
- `update_links` - Update links after rename

### Tag Operations (4)
- `get_all_tags` - List all tags with counts
- `add_tags` - Add tags to notes
- `remove_tags` - Remove tags from notes
- `rename_tag` - Rename tag across vault

### Git Operations (5)
- `git_status` - Get git status
- `git_commit` - Commit changes
- `git_pull` - Pull from remote
- `git_push` - Push to remote
- `git_history` - Get commit history

### Vault Operations (5+)
- `get_vault_stats` - Get vault statistics
- `list_notes` - List all notes
- `get_vault_structure` - Get directory structure
- `find_orphaned_notes` - Find notes without links
- And more...

## Development

### Project Structure
```
obsidian-mcp-server/
├── cmd/obsidian-mcp/          # Entry point
├── internal/
│   ├── domain/                # Domain entities
│   ├── repository/            # Repository interfaces
│   ├── usecase/              # Business logic
│   ├── infrastructure/       # External dependencies
│   ├── adapter/mcp/          # MCP protocol layer
│   └── config/               # Configuration
├── pkg/                      # Public packages
└── test/                     # Tests
```

### Building
```bash
go build -o obsidian-mcp ./cmd/obsidian-mcp
```

### Testing
```bash
go test ./...
```

### Contributing
1. Fork the repository
2. Create feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit pull request

## Performance

### Target Metrics
- Read operations: < 100ms
- Create/Update: < 200ms
- Search (5000 notes): < 500ms
- Memory usage: ~200MB for 5000 notes

### Scalability
- Recommended: Up to 10,000 notes
- Maximum: 50,000 notes (performance may degrade)
- Vault size: Up to 1GB

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/user/obsidian-mcp-server/issues)
- **Documentation**: [Wiki](https://github.com/user/obsidian-mcp-server/wiki)
- **Discussions**: [GitHub Discussions](https://github.com/user/obsidian-mcp-server/discussions)

## Roadmap

### v1.1.0
- [ ] Semantic search with embeddings
- [ ] Real-time file watching
- [ ] Web UI for monitoring

### v1.2.0
- [ ] Custom parsers
- [ ] Advanced git operations
- [ ] Performance improvements

### v2.0.0
- [ ] Multi-vault support
- [ ] Collaboration features
- [ ] Cloud sync integration