Obsidian MCP Server

Instructions

Implementation Reference

• src/tools/notes.ts:89-141 (handler)

  The handler function `handleListNotes` that validates the vault, lists markdown files, extracts metadata including titles from frontmatter or first H1 heading, and returns structured note list.

  export async function handleListNotes(
    vaultManager: VaultManager,
    vaultPath: string,
    folderPath?: string
  ) {
    await vaultManager.validateVault(vaultPath);
    
    const files = await vaultManager.listMarkdownFiles(vaultPath, folderPath);
    
    const notes = await Promise.all(
      files.map(async (file) => {
        try {
          const filePath = path.join(vaultPath, file);
          const stats = await fs.stat(filePath);
          
          // Try to extract title from frontmatter or first heading
          let title = path.basename(file, '.md');
          try {
            const content = await fs.readFile(filePath, 'utf-8');
            const parsed = matter(content);
            
            if (parsed.data.title) {
              title = parsed.data.title;
            } else {
              // Look for first # heading
              const match = parsed.content.match(/^#\s+(.+)$/m);
              if (match) {
                title = match[1];
              }
            }
          } catch {
            // Ignore errors reading file content
          }
          
          return {
            path: file,
            title,
            modified: stats.mtime,
            size: stats.size,
          };
        } catch (error) {
          logger.warn(`Could not process file ${file}:`, error);
          return null;
        }
      })
    );
    
    return {
      vault: vaultPath,
      folder: folderPath,
      notes: notes.filter(n => n !== null),
    };
  }

• src/index.ts:107-120 (schema)

  Input schema for the `list_notes` tool, defining parameters vault_path (required) and optional folder_path.

  inputSchema: {
    type: 'object',
    properties: {
      vault_path: {
        type: 'string',
        description: 'Path to the Obsidian vault',
      },
      folder_path: {
        type: 'string',
        description: 'Optional folder path within vault',
      },
    },
    required: ['vault_path'],
  },

• src/index.ts:104-121 (registration)

  Registration of the `list_notes` tool in the TOOLS array, including name, description, and input schema.

  {
    name: 'list_notes',
    description: 'List all notes in a vault or folder',
    inputSchema: {
      type: 'object',
      properties: {
        vault_path: {
          type: 'string',
          description: 'Path to the Obsidian vault',
        },
        folder_path: {
          type: 'string',
          description: 'Optional folder path within vault',
        },
      },
      required: ['vault_path'],
    },
  },

• src/index.ts:203-208 (registration)

  Tool dispatch in the switch statement for CallToolRequestSchema, calling the handleListNotes handler with validated arguments.

  case 'list_notes':
    if (!args || typeof args !== 'object' || !('vault_path' in args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Missing vault_path');
    }
    result = await handleListNotes(vaultManager, args.vault_path as string, args.folder_path as string | undefined);
    break;