README.md•8.73 kB
# Obsidian Local REST API MCP Server
An AI-Native MCP (Model Context Protocol) server that provides intelligent, task-oriented tools for interacting with Obsidian vaults through a local REST API.
## 🧠 AI-Native Design Philosophy
This MCP server has been redesigned following AI-Native principles rather than simple API-to-tool mapping. Instead of exposing low-level CRUD operations, it provides high-level, task-oriented tools that LLMs can reason about more effectively.
### Before vs After: The Transformation
| **Old Approach (CRUD-Based)** | **New Approach (AI-Native)** | **Why Better** |
|--------------------------------|-------------------------------|----------------|
| `list_files` (returns everything) | `list_directory(path, limit, offset)` | Prevents context overflow with pagination |
| `create_file` + `update_file` | `write_file(path, content, mode)` | Single tool handles create/update/append |
| `create_note` + `update_note` | `create_or_update_note(path, content, frontmatter)` | Intelligent upsert removes decision complexity |
| `search_notes(query)` | `search_vault(query, scope, path_filter)` | Precise, scopeable search with advanced filtering |
| *(no equivalent)* | `get_daily_note(date)` | High-level abstraction for common workflow |
| *(no equivalent)* | `get_recent_notes(limit)` | Task-oriented recent file access |
| *(no equivalent)* | `find_related_notes(path, on)` | Conceptual relationship discovery |
## 🛠 Available Tools
### Directory & File Operations
#### `list_directory`
**Purpose**: List directory contents with pagination to prevent context overflow
```json
{
"path": "Projects/",
"recursive": false,
"limit": 20,
"offset": 0
}
```
**AI Benefit**: LLM can explore vault structure incrementally without overwhelming context
#### `read_file`
**Purpose**: Read content of any file in the vault
```json
{"path": "notes/meeting-notes.md"}
```
#### `write_file`
**Purpose**: Write file with multiple modes - replaces separate create/update operations
```json
{
"path": "notes/summary.md",
"content": "# Meeting Summary\n...",
"mode": "append" // "overwrite", "append", "prepend"
}
```
**AI Benefit**: Single tool handles all write scenarios, removes ambiguity
#### `delete_item`
**Purpose**: Delete any file or directory
```json
{"path": "old-notes/"}
```
### AI-Native Note Operations
#### `create_or_update_note`
**Purpose**: Intelligent upsert - creates if missing, updates if exists
```json
{
"path": "daily/2024-12-26",
"content": "## Tasks\n- Review AI-native MCP design",
"frontmatter": {"tags": ["daily", "tasks"]}
}
```
**AI Benefit**: Eliminates "does this note exist?" decision tree
#### `get_daily_note`
**Purpose**: Smart daily note retrieval with common naming patterns
```json
{"date": "today"} // or "yesterday", "2024-12-26"
```
**AI Benefit**: Abstracts file system details and naming conventions
#### `get_recent_notes`
**Purpose**: Get recently modified notes
```json
{"limit": 5}
```
**AI Benefit**: Matches natural "what did I work on recently?" queries
### Advanced Search & Discovery
#### `search_vault`
**Purpose**: Multi-scope search with advanced filtering
```json
{
"query": "machine learning",
"scope": ["content", "filename", "tags"],
"path_filter": "research/"
}
```
**AI Benefit**: Precise, targeted search reduces noise
#### `find_related_notes`
**Purpose**: Discover conceptual relationships between notes
```json
{
"path": "ai-research.md",
"on": ["tags", "links"]
}
```
**AI Benefit**: Enables relationship-based workflows and serendipitous discovery
### Legacy Tools (Backward Compatibility)
The server maintains backward compatibility with existing tools like `get_note`, `list_notes`, `get_metadata_keys`, etc.
## Prerequisites
- Node.js 18+ or Bun runtime
- [Obsidian Local REST API](https://github.com/j-shelfwood/obsidian-local-rest-api) running locally (default: http://obsidian-local-rest-api.test)
## Installation
### Using npx (Recommended)
```bash
npx obsidian-local-rest-api-mcp
```
### From Source
```bash
# Clone the repository
git clone https://github.com/j-shelfwood/obsidian-local-rest-api-mcp.git
cd obsidian-local-rest-api-mcp
# Install dependencies with bun
bun install
# Build the project
bun run build
```
## Configuration
Set environment variables for API connection:
```bash
export OBSIDIAN_API_URL="http://obsidian-local-rest-api.test" # Default URL (or http://localhost:8000 for non-Valet setups)
export OBSIDIAN_API_KEY="your-api-key" # Optional bearer token
```
## Usage
### Running the Server
```bash
# Development mode with auto-reload
bun run dev
# Production mode
bun run start
# Or run directly
node build/index.js
```
### MCP Client Configuration
#### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"obsidian-vault": {
"command": "npx",
"args": ["obsidian-local-rest-api-mcp"],
"env": {
"OBSIDIAN_API_URL": "http://obsidian-local-rest-api.test",
"OBSIDIAN_API_KEY": "your-api-key-if-needed"
}
}
}
}
```
#### VS Code with MCP Extension
Use the included `.vscode/mcp.json` configuration file.
## Development
```bash
# Watch mode for development
bun run dev
# Build TypeScript
bun run build
# Type checking
bun run tsc --noEmit
```
## Architecture
- **ObsidianApiClient** - HTTP client wrapper for REST API endpoints
- **ObsidianMcpServer** - MCP server implementation with tool handlers
- **Configuration** - Environment-based configuration with validation
## Error Handling
The server includes comprehensive error handling:
- API connection failures
- Invalid tool parameters
- Network timeouts
- Authentication errors
Errors are returned as MCP tool call responses with descriptive messages.
## Debugging
Enable debug logging by setting environment variables:
```bash
export DEBUG=1
export NODE_ENV=development
```
Server logs are written to stderr to avoid interfering with MCP protocol communication on stdout.
## Troubleshooting
### MCP Server Fails to Start
If your MCP client shows "Start Failed" or similar errors:
1. **Test the server directly**:
```bash
npx obsidian-local-rest-api-mcp --version
```
Should output the version number.
2. **Test MCP protocol**:
```bash
# Run our test script
node -e "
const { spawn } = require('child_process');
const child = spawn('npx', ['obsidian-local-rest-api-mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
child.stdout.on('data', d => console.log('OUT:', d.toString()));
child.stderr.on('data', d => console.log('ERR:', d.toString()));
setTimeout(() => {
child.stdin.write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1.0.0'}}})+'\n');
setTimeout(() => child.kill(), 2000);
}, 500);
"
```
Should show initialization response.
3. **Check Environment Variables**:
- Ensure `OBSIDIAN_API_URL` points to a running Obsidian Local REST API
- Test the API directly: `curl http://obsidian-local-rest-api.test/api/files` (or your configured API URL)
4. **Verify Obsidian Local REST API**:
- Install and run [Obsidian Local REST API](https://github.com/j-shelfwood/obsidian-local-rest-api)
- Confirm it's accessible on the configured port
- Check if authentication is required
### Common Issues
**"Command not found"**: Make sure Node.js/npm is installed and npx is available
**"Connection refused"**: Obsidian Local REST API is not running or wrong URL
**Laravel Valet .test domains**: If using Laravel Valet, ensure your project directory name matches the .test domain (e.g., `obsidian-local-rest-api.test` for a project in `/obsidian-local-rest-api/`)
**"Unauthorized"**: Check if API key is required and properly configured
**"Timeout"**: Increase timeout in client configuration or check network connectivity
### Cherry Studio Configuration
For Cherry Studio, use these exact settings:
- **Name**: `obsidian-vault` (or any name you prefer)
- **Type**: `Standard Input/Output (stdio)`
- **Command**: `npx`
- **Arguments**: `obsidian-local-rest-api-mcp`
- **Environment Variables**:
- `OBSIDIAN_API_URL`: Your API URL (e.g., `http://obsidian-local-rest-api.test` for Laravel Valet)
- `OBSIDIAN_API_KEY`: Optional API key if authentication is required
- **Environment Variables**:
- `OBSIDIAN_API_URL`: `http://obsidian-local-rest-api.test` (or your API URL)
- `OBSIDIAN_API_KEY`: `your-api-key` (if required)
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make changes with proper TypeScript types
4. Test with your Obsidian vault
5. Submit a pull request
## License
MIT