Obsidian MCP Server

Instructions

Implementation Reference

• src/tools/notes.ts:40-87 (handler)

  The core handler function for the 'write_note' tool. It validates the vault, ensures the directory exists, handles different write modes (overwrite, append, prepend with frontmatter awareness), writes the file, and returns success status.

  export async function handleWriteNote(
    vaultManager: VaultManager,
    vaultPath: string,
    notePath: string,
    content: string,
    mode: 'overwrite' | 'append' | 'prepend' = 'overwrite'
  ) {
    await vaultManager.validateVault(vaultPath);
    
    const filePath = vaultManager.getFilePath(vaultPath, notePath);
    
    // Ensure directory exists
    const dir = path.dirname(filePath);
    await fs.mkdir(dir, { recursive: true });
    
    let finalContent = content;
    
    if (mode !== 'overwrite') {
      try {
        const existing = await fs.readFile(filePath, 'utf-8');
        
        if (mode === 'append') {
          finalContent = existing + '\n' + content;
        } else if (mode === 'prepend') {
          // If the existing content has frontmatter, insert after it
          const parsed = matter(existing);
          if (Object.keys(parsed.data).length > 0) {
            finalContent = parsed.matter + '\n' + content + '\n' + parsed.content;
          } else {
            finalContent = content + '\n' + existing;
          }
        }
      } catch (error: any) {
        // File doesn't exist, just write the content
        if (error.code !== 'ENOENT') {
          throw error;
        }
      }
    }
    
    await fs.writeFile(filePath, finalContent, 'utf-8');
    
    return {
      path: notePath,
      success: true,
      mode,
    };
  }

• src/index.ts:76-103 (schema)

  The tool schema definition including name, description, and input schema for validation in the TOOLS array used for listing tools.

  {
    name: 'write_note',
    description: 'Create or update a note in the vault',
    inputSchema: {
      type: 'object',
      properties: {
        vault_path: {
          type: 'string',
          description: 'Path to the Obsidian vault',
        },
        note_path: {
          type: 'string',
          description: 'Path to the note relative to vault root',
        },
        content: {
          type: 'string',
          description: 'Content of the note',
        },
        mode: {
          type: 'string',
          enum: ['overwrite', 'append', 'prepend'],
          description: 'How to handle existing content',
          default: 'overwrite',
        },
      },
      required: ['vault_path', 'note_path', 'content'],
    },
  },

• src/index.ts:190-201 (registration)

  Registration in the switch statement that dispatches calls to the handleWriteNote handler with parameter validation.

  case 'write_note':
    if (!args || typeof args !== 'object' || !('vault_path' in args) || !('note_path' in args) || !('content' in args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Missing required parameters');
    }
    result = await handleWriteNote(
      vaultManager,
      args.vault_path as string,
      args.note_path as string,
      args.content as string,
      (args.mode as 'overwrite' | 'append' | 'prepend') || 'overwrite'
    );
    break;

• src/index.ts:14-14 (registration)

  Import statement registering the handleWriteNote function from the notes module.

  import { handleReadNote, handleWriteNote, handleListNotes } from './tools/notes.js';