ObsiScripta Bridge

ObsiScripta Bridge is a monorepo for an Obsidian plugin + stdio MCP bridge that enables MCP-based operations on your vault. It is designed to be script-extensible, so you can add your own custom tools with JavaScript/TypeScript.

[!IMPORTANT]

• Desktop Obsidian only (no mobile support).
• Script extensions run with full Obsidian API access and no sandbox.
• Bridge Protocol v1 has no authentication (kept for compatibility).
• MCP Standard endpoint requires API key authentication.

What you can do

• Use the MCP Standard HTTP API (JSON-RPC 2.0)
• Keep using the legacy Bridge Protocol v1 HTTP API for compatibility
• Run built-in note tools (read + edit operations)
• Add custom tools in JavaScript / TypeScript
• Hot-reload tools from mcp-tools/

Monorepo layout

• packages/obsidian-plugin/ Obsidian plugin implementation (hosts the local HTTP server)
• packages/stdio-bridge/ MCP stdio bridge (obsidian-mcp CLI), forwarding requests to the plugin HTTP server
• packages/shared/ Shared types and protocol interfaces
• examples/ Script tool examples
• docs/ Protocol and project documentation

Architecture overview

1. The Obsidian plugin starts a local HTTP server.
2. The stdio bridge connects to MCP clients (for example, Claude Desktop).
3. The stdio bridge forwards requests to the plugin via HTTP.
4. Tool execution is handled by built-in tools and/or script tools.

The stdio bridge supports three transport modes:

• auto (default): prefer MCP Standard, then fall back to Bridge v1
• mcp: MCP Standard only
• v1: Bridge Protocol v1 only

Setup

Prerequisites

• Node.js (LTS recommended)
• pnpm (this repository uses pnpm workspace)
• Obsidian Desktop

Development

pnpm install
pnpm run dev

Then reload Obsidian and enable the plugin in Settings → Community plugins.

Build

pnpm run build

Common commands

Root (across packages)

pnpm run dev
pnpm run build
pnpm run lint
pnpm run test
pnpm run test:integration

Per package

pnpm --filter obsiscripta-bridge-plugin run dev
pnpm --filter obsiscripta-bridge-plugin run build
pnpm --filter obsiscripta-bridge-plugin run lint

pnpm --filter obsidian-mcp-bridge run dev
pnpm --filter obsidian-mcp-bridge run build
pnpm --filter obsidian-mcp-bridge run build:binary

pnpm --filter @obsiscripta/shared run build

Installation

Manual install

Copy the following files into your vault plugin directory:

<Vault>/.obsidian/plugins/obsidian-mcp/
  main.js
  manifest.json
  styles.css

Install via BRAT

1. Install and enable BRAT.
2. Open Settings → BRAT → Add Beta plugin.
3. Enter this repository URL (example: https://github.com/daichi-629/obsidian-obsiscripta-mcp).
4. Go back to Settings → Community plugins and enable ObsiScripta Bridge.

Endpoints

The plugin exposes both protocols at the same time:

1. MCP Standard HTTP (recommended) http://127.0.0.1:3000/mcp

   • JSON-RPC 2.0
   • MCP specification 2025-03-26
   • API key required (X-ObsiScripta-Api-Key or Authorization: Bearer ...)

2. Bridge Protocol v1 (legacy compatibility) http://127.0.0.1:3000/bridge/v1

   • Custom legacy HTTP API
   • No authentication (for v1 compatibility)

See docs/protocol.md for details.

Claude Desktop configuration (stdio bridge)

1. Open Settings → Community plugins → ObsiScripta Bridge in Obsidian.
2. Confirm host/port in Connection info (example: 127.0.0.1:3000).
3. Create an MCP API key in plugin settings.
4. Download the obsidian-mcp binary for your OS from the project distribution assets.
5. Add the server entry to your Claude Desktop MCP config:

{
	"mcpServers": {
		"obsidian": {
			"command": "/path/to/obsidian-mcp",
			"env": {
				"OBSIDIAN_MCP_HOST": "127.0.0.1",
				"OBSIDIAN_MCP_PORT": "3000",
				"OBSIDIAN_MCP_API_KEY": "obsi_...",
				"OBSIDIAN_MCP_TRANSPORT": "auto"
			}
		}
	}
}

If you change the port, run Restart server in the plugin and update OBSIDIAN_MCP_PORT accordingly.

Script tools

By default, script tools are loaded from mcp-tools/ at your vault root (configurable in settings):

mcp-tools/

Minimal example:

export default {
	// Tool name is derived from file path.
	// mcp-tools/example_tool.js -> example_tool
	// mcp-tools/utils/helper.js -> utils/helper
	description: "Example custom tool",
	inputSchema: {
		type: "object",
		properties: {
			query: { type: "string" },
		},
		required: ["query"],
	},
	handler: async (args, context) => {
		const files = context.vault.getMarkdownFiles();
		return {
			content: [{ type: "text", text: `Found ${files.length} files` }],
		};
	},
};

Notes:

• Relative imports resolve from the script file location.
• CommonJS require(...) can also be used in script tools (Node built-ins like path / fs, and local CommonJS files).
• If Dataview is installed, dv (Dataview API) is available.
• If Templater is installed, tp (Templater API) is available.
• If Omnisearch is installed, the global omnisearch API is available.

Detailed require example:

Place the following two files under mcp-tools/.

mcp-tools/require_example.js

export default {
	description: "Exercise require-based module loading from a helper module.",
	inputSchema: {
		type: "object",
		properties: {
			name: { type: "string" },
		},
	},
	handler: async (args) => {
		const helper = require("./require-helper");
		const message = typeof helper?.buildMessage === "function"
			? helper.buildMessage(args?.name)
			: "require helper missing buildMessage";

		return {
			content: [
				{
					type: "text",
					text: message,
				},
			],
		};
	},
};

mcp-tools/require-helper.js

const buildMessage = (name) => {
	const value = typeof name === "string" && name.trim() ? name.trim() : "world";
	return `require-ok: hello ${value}`;
};

module.exports = {
	buildMessage,
};

Example input:

{ "name": "Obsidian" }

Example output (content[0].text):

require-ok: hello Obsidian

Examples:

• examples/dataview-example.js
• examples/templater-example.js
• examples/omnisearch-example.js

Testing

pnpm run test
pnpm run test:integration

Integration tests are organized under packages/integration-tests.

References

• Obsidian API docs: https://docs.obsidian.md