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

# 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

go install github.com/user/obsidian-mcp-server/cmd/obsidian-mcp@latest

Docker

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

Quick Start

1. Configure MCP Client (Claude Desktop example):

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp",
      "args": ["--vault", "/path/to/your/vault"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

2. Start the server:

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

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)

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

go build -o obsidian-mcp ./cmd/obsidian-mcp

Testing

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 file for details.

Support

• Issues: GitHub Issues
• Documentation: Wiki
• Discussions: GitHub 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