Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/SamBleed/opencode-obsidian/llms.txt

Use this file to discover all available pages before exploring further.

Bunker OS uses two Model Context Protocol (MCP) servers to give OpenCode skills persistent reach beyond the in-session context window. The obsidian-vault server gives skills direct read/write access to the Obsidian vault — creating and updating wiki notes without copy-paste. The n8n-mcp server gives skills “hands” to trigger async n8n pipelines, so an agent can fire the AOC v4 Enterprise webhook or check workflow status without leaving the OpenCode session. Both servers are configured in a single JSON file on your local machine.

​
The Two MCP Servers

obsidian-vault

Direct read/write access to your Obsidian vault. Used by autoresearch, wiki-ingest, wiki-query, wiki-lint, and save skills to create and update wiki notes.

n8n-mcp

Connects OpenCode to the n8n instance running at localhost:5678. Exposes n8n workflow operations as MCP tools so skills can trigger pipelines programmatically.

​
OpenCode Config File

Both MCP servers are declared in the mcp block of ~/.config/opencode/opencode.json. This file is read by OpenCode on startup and applies globally across all projects. Valid server shapes are:
  • type: "local" with a command array — for local process servers (e.g., uvx, npx)
  • type: "remote" with a url — for HTTP-based servers like n8n’s built-in MCP endpoint
  • enabled: true | false — optional flag to toggle a server without removing it
  • headers — allowed only for type: "remote"
  • oauth — allowed only for type: "remote"
The old type: "http" shape is invalid in current OpenCode versions. Using it causes OpenCode to fail on startup with Invalid input mcp.n8n-mcp. Always use type: "remote" for HTTP-based servers. This was the root cause of a known startup regression — see the Troubleshooting section below.

​
Configuring n8n MCP

​
Step 1: Enable MCP in n8n

In the n8n UI go to Settings → AI and enable “Enable instance-level MCP access”. This activates the /mcp-server/http endpoint at localhost:5678.

​
Step 2: Add the n8n-mcp block to opencode.json

The exact working configuration: 
{
  "mcp": {
    "n8n-mcp": {
      "type": "remote",
      "url": "http://localhost:5678/mcp-server/http",
      "enabled": true,
      "oauth": false
    }
  }
}
1

Open your OpenCode config

$EDITOR ~/.config/opencode/opencode.json
If the file does not exist, create it with the JSON above as the full contents.
2

Add the n8n-mcp server block

Merge the n8n-mcp entry into the existing mcp block if you already have other servers configured. Do not replace the entire file.
3

Start OpenCode and authenticate

opencode mcp auth n8n-mcp
OpenCode will open an OAuth flow in your browser. Complete the login and OpenCode stores the auth state separately from the config file.
4

Verify the connection

opencode mcp list          # shows all configured MCP servers
opencode mcp auth list     # shows authentication status
opencode mcp debug n8n-mcp # tests the connection end-to-end
A successful result shows n8n-mcp authenticated in auth list and Connection successful (already authenticated) in debug.
The 401 Unauthorized response you see during the first opencode mcp debug n8n-mcp probe is expected and does not mean the MCP is broken. OpenCode intentionally calls the server without credentials on the first probe to detect the auth flow type. The sequence is: 401 Unauthorized → OAuth redirect → success after login. The final state is what matters.

​
Configuring obsidian-vault MCP

The obsidian-vault MCP server gives skills direct access to vault notes. There are two options depending on whether you want to install an Obsidian plugin.

​
Option A — REST API (mcp-obsidian)

Requires the Local REST API community plugin installed and enabled in Obsidian. The plugin runs on https://127.0.0.1:27124 with a self-signed certificate. Install the plugin:
  1. Obsidian → Settings → Community Plugins → Turn off Restricted Mode
  2. Browse → Search “Local REST API” → Install → Enable
  3. Settings → Local REST API → Copy the API key
Configure the MCP server by adding the obsidian-vault block to ~/.config/opencode/opencode.json: 
{
  "mcp": {
    "obsidian-vault": {
      "type": "local",
      "command": ["uvx", "mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "your-key-here",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}
Test the plugin is running before configuring: 
curl -sk -H "Authorization: Bearer <YOUR_KEY>" https://127.0.0.1:27124/
You should receive a JSON response with vault info.

​
Option B — Filesystem (MCPVault, no plugin needed)

Reads the vault directory directly from the filesystem. No Obsidian plugin required. Add the obsidian-vault block to ~/.config/opencode/opencode.json: 
{
  "mcp": {
    "obsidian-vault": {
      "type": "local",
      "command": ["npx", "-y", "@bitbonsai/mcpvault@latest", "/absolute/path/to/your/vault"]
    }
  }
}
Replace /absolute/path/to/your/vault with the actual path to your opencode-obsidian directory. Both options are configured in ~/.config/opencode/opencode.json, which applies globally across all OpenCode projects on your machine.

​
MCP Tools Available to Skills

Once obsidian-vault is configured, the following tools become available to all skills in OpenCode sessions:
ToolPurpose
obsidian-vault_read_noteRead the full content of a vault note by path
obsidian-vault_write_noteCreate or overwrite a vault note
obsidian-vault_search_notesFull-text search across all vault notes
obsidian-vault_patch_noteSurgical edit — append or replace under a heading
obsidian-vault_list_directoryList notes and folders at a vault path
obsidian-vault_update_frontmatterUpdate YAML frontmatter fields without touching the body
obsidian-vault_get_notes_infoGet metadata (frontmatter, size, dates) for one or more notes
These are the tools used by autoresearch to file research pages, by wiki-ingest to create entity and concept pages, and by save to persist conversation summaries — all without copy-paste.

​
Troubleshooting

​
OpenCode won’t start after editing opencode.json

Check that the config uses type: "remote" (not type: "http"). The type: "http" shape was valid in older OpenCode versions but was removed. The error message is: 
Invalid input mcp.n8n-mcp
Fix: replace "type": "http" with "type": "remote" and remove any headers block (use OAuth instead for auth).

​
OpenCode is stuck on startup with a WAL error

If OpenCode fails before it even reaches the MCP configuration step with a message like: 
Failed to run the query 'PRAGMA wal_checkpoint(PASSIVE)'
Run the WAL checkpoint fix: 
sqlite3 ~/.local/share/opencode/opencode.db 'PRAGMA wal_checkpoint(TRUNCATE);'
This clears the WAL file and allows OpenCode to start. After running the command, the WAL file drops to zero bytes and OpenCode launches normally.

​
n8n MCP shows 401 after authentication

The 401 on the first probe is expected (see the Note above). If you see a persistent 401 after completing the OAuth flow, re-authenticate: 
opencode mcp auth n8n-mcp
Then verify with: 
opencode mcp debug n8n-mcp

​
obsidian-vault tools not appearing in session

Confirm the server is registered and active: 
opencode mcp list
If the server appears but tools are missing, check that the Local REST API plugin is running in Obsidian (Option A) or that the vault path is correct (Option B).

n8n Overview

Start here for n8n Docker setup before configuring the MCP bridge.

AOC Pipeline

Trigger the AOC v4 pipeline from OpenCode skills via n8n-mcp.

Dead Letter Queue

Capture errors from MCP-triggered workflow executions.

Build docs developers (and LLMs) love

Get started for freeTalk to us