110 lines
3.1 KiB
Markdown
110 lines
3.1 KiB
Markdown
|
# Obsidian MCP Server Configuration
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
This document describes how to configure the [cyanheads/obsidian-mcp-server](https://github.com/cyanheads/obsidian-mcp-server) for use with Opencode. This MCP server enables AI agents to interact with the Obsidian vault via the Local REST API plugin.
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
1. **Obsidian Desktop App** - Must be running
|
||
|
|
2. **Local REST API Plugin** - Installed and enabled in Obsidian
|
||
|
|
3. **API Key** - Generated from plugin settings
|
||
|
|
|
||
|
|
## Environment Variables
|
||
|
|
|
||
|
|
| Variable | Description | Default | Required |
|
||
|
|
|----------|-------------|---------|----------|
|
||
|
|
| `OBSIDIAN_API_KEY` | API key from Local REST API plugin | - | Yes |
|
||
|
|
| `OBSIDIAN_BASE_URL` | Base URL for REST API | `http://127.0.0.1:27123` | No |
|
||
|
|
| `OBSIDIAN_VERIFY_SSL` | Verify SSL certificates | `false` | No |
|
||
|
|
| `OBSIDIAN_ENABLE_CACHE` | Enable vault caching | `true` | No |
|
||
|
|
|
||
|
|
## opencode.json Configuration
|
||
|
|
|
||
|
|
Add this to your `programs.opencode.settings.mcp` in your Nix home-manager config:
|
||
|
|
|
||
|
|
```json
|
||
|
|
"Obsidian-Vault": {
|
||
|
|
"command": ["npx", "obsidian-mcp-server"],
|
||
|
|
"environment": {
|
||
|
|
"OBSIDIAN_API_KEY": "<your-api-key>",
|
||
|
|
"OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
|
||
|
|
"OBSIDIAN_VERIFY_SSL": "false",
|
||
|
|
"OBSIDIAN_ENABLE_CACHE": "true"
|
||
|
|
},
|
||
|
|
"enabled": true,
|
||
|
|
"type": "local"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**Note**: Replace `<your-api-key>` with the key from Obsidian Settings → Local REST API.
|
||
|
|
|
||
|
|
## Nix Home-Manager Integration
|
||
|
|
|
||
|
|
In your NixOS/home-manager configuration:
|
||
|
|
|
||
|
|
```nix
|
||
|
|
programs.opencode.settings.mcp = {
|
||
|
|
# ... other MCP servers ...
|
||
|
|
|
||
|
|
"Obsidian-Vault" = {
|
||
|
|
command = ["npx" "obsidian-mcp-server"];
|
||
|
|
environment = {
|
||
|
|
OBSIDIAN_API_KEY = "<your-api-key>";
|
||
|
|
OBSIDIAN_BASE_URL = "http://127.0.0.1:27123";
|
||
|
|
OBSIDIAN_VERIFY_SSL = "false";
|
||
|
|
OBSIDIAN_ENABLE_CACHE = "true";
|
||
|
|
};
|
||
|
|
enabled = true;
|
||
|
|
type = "local";
|
||
|
|
};
|
||
|
|
};
|
||
|
|
```
|
||
|
|
|
||
|
|
After updating, run:
|
||
|
|
```bash
|
||
|
|
home-manager switch
|
||
|
|
```
|
||
|
|
|
||
|
|
## Getting the API Key
|
||
|
|
|
||
|
|
1. Open Obsidian Settings
|
||
|
|
2. Navigate to Community Plugins → Local REST API
|
||
|
|
3. Copy the API key shown in settings
|
||
|
|
4. Paste into your configuration
|
||
|
|
|
||
|
|
## Available MCP Tools
|
||
|
|
|
||
|
|
Once configured, these tools are available:
|
||
|
|
|
||
|
|
| Tool | Description |
|
||
|
|
|------|-------------|
|
||
|
|
| `obsidian_read_note` | Read a note's content |
|
||
|
|
| `obsidian_update_note` | Create or update a note |
|
||
|
|
| `obsidian_global_search` | Search the entire vault |
|
||
|
|
| `obsidian_manage_frontmatter` | Get/set frontmatter fields |
|
||
|
|
| `obsidian_manage_tags` | Add/remove tags |
|
||
|
|
| `obsidian_list_notes` | List notes in a folder |
|
||
|
|
| `obsidian_delete_note` | Delete a note |
|
||
|
|
| `obsidian_search_replace` | Search and replace in a note |
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
### Server not responding
|
||
|
|
- Ensure Obsidian desktop app is running
|
||
|
|
- Check Local REST API plugin is enabled
|
||
|
|
- Verify API key matches
|
||
|
|
|
||
|
|
### Connection refused
|
||
|
|
- Check the base URL (default: `http://127.0.0.1:27123`)
|
||
|
|
- Some setups use port 27124 - check plugin settings
|
||
|
|
|
||
|
|
### npx not found
|
||
|
|
- Ensure Node.js is installed
|
||
|
|
- Run `npm install -g npx` if needed
|
||
|
|
|
||
|
|
## References
|
||
|
|
|
||
|
|
- [cyanheads/obsidian-mcp-server GitHub](https://github.com/cyanheads/obsidian-mcp-server)
|
||
|
|
- [Obsidian Local REST API Plugin](https://github.com/czottmann/obsidian-local-rest-api)
|