From 1e03c165e7d65e3e8e346e61e1a7b8aa77b90bc2 Mon Sep 17 00:00:00 2001
From: m3tm3re <p@m3ta.dev>
Date: Thu, 12 Feb 2026 19:44:03 +0100
Subject: [PATCH] docs: Add Obsidian MCP server configuration documentation

- Create mcp-config.md in skills/memory/references/
- Document cyanheads/obsidian-mcp-server setup for Opencode
- Include environment variables, Nix config, and troubleshooting
- Reference for Task 4 of memory-system plan
---
 skills/memory/references/mcp-config.md | 109 +++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 skills/memory/references/mcp-config.md

diff --git a/skills/memory/references/mcp-config.md b/skills/memory/references/mcp-config.md
new file mode 100644
index 0000000..2e4de3e
--- /dev/null
+++ b/skills/memory/references/mcp-config.md
@@ -0,0 +1,109 @@
+# 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)