obsidian-mcp-server

The obsidian-mcp-server provides fourteen tools categorized by their primary function to allow an agent to interact with an Obsidian vault:

• Readers: Fetch notes and metadata using obsidian_get_note, obsidian_list_notes, obsidian_list_tags, and obsidian_search_notes.
• Writers: Create or surgically edit content using obsidian_write_note, obsidian_append_to_note, obsidian_patch_note, and obsidian_replace_in_note.
• Managers: Reconcile tags and frontmatter using obsidian_manage_tags and obsidian_manage_frontmatter.
• Command Execution: A guarded escape hatch to dispatch Obsidian command-palette commands via obsidian_execute_command and obsidian_list_commands (requires opt-in).
• Other: obsidian_delete_note for file removal and obsidian_open_in_ui to open files in the Obsidian app.

The repository is organized into the following key directories:

Every tool and resource handler in @cyanheads/mcp-ts-core receives a single Context (ctx) argument. This object provides the necessary infrastructure for the current request, including identity, structured logging, tenant-scoped storage, cancellation signals, and task progress.

Key Mental Model:

• Use ctx.log for logging events related to the specific request.
• Use ctx.state for storing data that should be scoped to the current tenant.
• Use the global logger or StorageService only for lifecycle code (like setup()) or background tasks where no request context exists.
• The framework automatically instruments handlers with OTel spans and metrics.

import type { Context } from '@cyanheads/mcp-ts-core';

// Every handler receives this:
async function myToolHandler(ctx: Context) {
  // ...
}

Configuration in @cyanheads/mcp-ts-core is split into two distinct layers that should never be merged. Understanding this distinction is critical for correctly managing environment variables and domain-specific settings:

1. Core Config: Managed by the framework. It is driven by environment variables and handles infrastructure-level settings (Identity, Transport, Auth, etc.).
2. Server Config: Managed by your specific implementation. You define this using your own Zod schema to handle domain-specific environment variables required by your MCP server.

To interact with the configuration system, import the necessary utilities from @cyanheads/mcp-ts-core/config.

import { AppConfig, config, parseConfig, resetConfig, ConfigSchema } from '@cyanheads/mcp-ts-core/config';

When preparing a release, determine the new version based on the nature of the changes in the diff:

Default to patch unless the changes clearly warrant a minor or major bump.

Anything sent to the client that reaches the LLM's context is a potential injection vector. This includes tool outputs, resource content, prompt text, and metadata used for tool selection.

What to check:

• Tool Outputs: Check *.tool.ts for output schemas and the format() method. Ensure untrusted content is wrapped in delimiters (e.g., blockquotes, <data> tags).
• Resource Content: Ensure resources/read content is framed similarly to tool outputs.
• Prompt Templates: Check *.prompt.ts for interpolation of untrusted data without escaping.
• Metadata/Descriptions: Ensure description, title, annotations, and inputSchema descriptions are static. Templated descriptions (e.g., description: Look up ${tenant.customLabel}``) enable "tool poisoning."

Different MCP clients read different surfaces:

• Claude Code reads structuredContent from output.
• Claude Desktop reads content[] from format().

To ensure every client sees the same data, you must maintain format parity. A thin format() that only returns a count or title will leave content[]-only clients blind to the actual data.

Best Practice: Use format-parity to ensure every field in output is also rendered in format() using structured markdown (headers, bold labels, lists) for readability.

Contextual Information: To ensure agent-facing context (like empty-result notices or pagination totals) reaches both surfaces, use an enrichment block via ctx.enrich(...). This automatically merges into structuredContent and is mirrored into the content[] trailer in format().

The server exposes several URI-based resources that clients can attach to conversations or inspect directly:

• obsidian://vault/{+path}: Represents a specific note. Provides content, frontmatter, tags, and file metadata.
• obsidian://tags: Provides all tags found across the entire vault, including usage counts. Note that tag listing is vault-wide and is not restricted by OBSIDIAN_READ_PATHS.
• obsidian://status: Provides server reachability, authentication status, plugin/Obsidian version information, and the plugin manifest.

The framework's instrumentation behavior varies depending on the runtime environment:

Node.js / Bun

• Node.js: Full NodeSDK support. Includes auto-instrumentation for HTTP servers (skipping /healthz) and Pino logs (injecting trace_id/span_id).
• Bun: NodeSDK works, but Node's HTTP auto-instrumentation is a no-op. To get HTTP coverage on Bun, you must install @hono/otel and use the httpInstrumentationMiddleware on the MCP endpoint. Manual spans, custom metrics, and OTLP export work normally.

Cloudflare Workers / V8 isolates

• NodeSDK is unavailable and initialization will silently no-op.
• While helper calls like createCounter, createHistogram, and withSpan will function via the global OTel API, they will produce no output unless you manually wire a Worker-compatible exporter and use ctx.waitUntil() to flush data.