# Obsidian Knowledge Management MCP Server
A local MCP (Model Context Protocol) server that provides stateless I/O access to Obsidian vaults. This server enables LLMs to read, analyze, and manage Obsidian markdown files, YAML frontmatter, and wikilinks.
## Key Features
- **Stateless I/O Layer**: Pure data access and atomic operations - no semantic analysis
- **35+ MCP Tools**: Comprehensive vault management across 5 categories
- **Frontmatter Management**: Parse, update, and validate YAML metadata
- **Wikilink Operations**: Extract, analyze, and manipulate `[[wikilinks]]`
- **Graph Operations**: Build link graphs, find backlinks, identify orphan notes
- **Full-Text Search**: Literal and regex pattern matching across vault
- **Security**: Path validation prevents directory traversal attacks
## Installation
```bash
npm install
npm run build
```
## Configuration
Create a `.env` file based on `.env.example`:
```bash
VAULT_PATH=./Test Vault
LOG_LEVEL=info
MAX_CONCURRENT_OPS=10
```
Or set environment variables when running:
```bash
VAULT_PATH="./Test Vault" node dist/index.js
```
## Usage
### Running the Server
The server uses stdio transport for MCP communication:
```bash
VAULT_PATH="./Test Vault" node dist/index.js
```
### Claude Desktop Integration
Add to your Claude Desktop MCP configuration:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"obsidian-knowledge": {
"command": "node",
"args": ["/absolute/path/to/obsidian-knowledge-mcp/dist/index.js"],
"env": {
"VAULT_PATH": "/absolute/path/to/your/vault"
}
}
}
}
```
## Available Tools (Phase 1 - Navigation)
### 1. list_notes
List all notes with optional filtering.
**Arguments**:
- `folder` (optional): Filter by folder path
- `tags` (optional): Array of tags (note must have all)
- `dateRange` (optional): `{ start, end }` in ISO format
- `offset` (optional): Skip N notes for pagination
- `limit` (optional): Return max N notes
**Example**:
```json
{
"folder": "Studies/MATH 31AH",
"tags": ["MATH31AH"],
"limit": 10
}
```
**Returns**: Array of `NoteMetadata` with path, title, created date, tags, modified date, size.
### 2. read_note
Read a note with full metadata.
**Arguments**:
- `path` (required): Vault-relative path (e.g., `"Studies/MATH 31AH/Vectors.md"`)
**Returns**:
- `content`: Full markdown content
- `frontmatter`: Parsed YAML (or null if missing/malformed)
- `frontmatterError`: Parse error message if YAML is malformed
- `outgoingLinks`: Array of wikilinks with target, alias, heading, line, column
- `headings`: Array of headings with level, text, line, id
- `stats`: Line count, character count, modified timestamp
### 3. read_notes_batch
Read multiple notes in one call.
**Arguments**:
- `paths` (required): Array of vault-relative paths
**Returns**: Array of `ReadNoteResult` (same as read_note)
### 4. search_notes
Full-text search across vault.
**Arguments**:
- `pattern` (required): Search string or regex
- `isRegex` (optional): Treat pattern as regex (default: false)
- `folder` (optional): Limit search to folder
- `limit` (optional): Max occurrences per note (default: 10)
**Returns**: Array of `SearchResult` with path, match count, and occurrences (with line, column, context).
### 5. get_vault_structure
Get folder hierarchy with note counts.
**Arguments**: None
**Returns**: `FolderNode` tree with path, name, note count, and children.
## Architecture
```
┌─────────────────────────────────────────┐
│ MCP Server (index.ts) │
│ - Tool registration │
│ - Request routing │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Tool Handlers (tools/*.ts) │
│ - navigation.ts - list, read, search │
│ - notes.ts - create, update, move │
│ - frontmatter.ts - get, update, bulk │
│ - links.ts - get links, backlinks │
│ - stats.ts - tags, titles │
└─────────────────────────────────────────┘
↓
┌──────────────────┬──────────────────────┐
│ Vault (vault.ts)│ Parser (parser.ts) │
│ - Path security │ - Frontmatter parse │
│ - File I/O │ - Wikilink extract │
│ - Validation │ - Heading extract │
└──────────────────┴──────────────────────┘
```
## Error Handling
The server returns structured errors with actionable suggestions:
```json
{
"success": false,
"error": {
"code": "FILE_NOT_FOUND",
"message": "File not found: nonexistent.md",
"context": { "path": "nonexistent.md" },
"actionable": "Use list_notes or get_note_titles to find available notes"
}
}
```
**Error Codes**:
- `PATH_OUTSIDE_VAULT`: Path contains `..` or escapes vault
- `FILE_NOT_FOUND`: File does not exist
- `FILE_LOCKED`: File in use by another process
- `INVALID_FRONTMATTER`: YAML parse error
- `INVALID_PATH`: Path contains illegal characters
## Development
### Building
```bash
npm run build # Compile TypeScript
npm run dev # Watch mode
```
### Testing
```bash
npm test # Run all tests
npm run test:unit # Unit tests only
npm run test:integration # Integration tests with Test Vault
```
### Linting
```bash
npm run lint
```
## Roadmap
### Phase 1: Foundation & Navigation (Completed)
- [x] MCP server initialization
- [x] Vault access with path security
- [x] Frontmatter and wikilink parsing
- [x] 5 navigation tools (list, read, search, structure)
### Phase 2: Note Management (Planned)
- [ ] create_note - Create with content + frontmatter
- [ ] update_note - Replace or patch sections
- [ ] move_note - Relocate + update backlinks
- [ ] delete_note - Remove + clean dangling references
### Phase 3: Frontmatter Operations (Planned)
- [ ] get_frontmatter - Parse metadata
- [ ] update_frontmatter - Modify fields
- [ ] bulk_update_frontmatter - Update across multiple notes
- [ ] audit_frontmatter - Validate against schema
### Phase 4: Link Operations (Planned)
- [ ] get_links - Outgoing wikilinks
- [ ] get_backlinks - Incoming links
- [ ] get_all_links - Complete link graph
- [ ] insert_link - Add wikilink
- [ ] get_orphan_notes - Notes with no links
- [ ] get_headings - Heading structure
- [ ] find_text_occurrences - Pattern matching
### Phase 5: Statistics & Polish (Planned)
- [ ] get_tag_list - All tags with counts
- [ ] get_note_titles - All titles + aliases
- [ ] Comprehensive documentation
- [ ] Integration tests
- [ ] Performance optimization
## Design Principles
1. **Stateless**: No caching, each call is independent
2. **Security**: Path validation prevents escapes
3. **Rich Metadata**: Include line numbers and positions for precise edits
4. **Graceful Degradation**: Malformed frontmatter returns with error flag
5. **SOLID Principles**: Clean separation of vault, parser, and tool layers
## License
MIT
## Contributing
Contributions welcome! This project follows SOLID principles and maintains a strict separation between the I/O layer (server) and intelligence layer (LLM).
