Obsidian Local REST API MCP Server

Instructions

Implementation Reference

• src/index.ts:246-248 (handler)

  Core implementation of the get_metadata_values tool in the ObsidianApiClient class. This method makes an HTTP request to the Obsidian REST API endpoint `/metadata/values/{key}` to retrieve unique values for the specified frontmatter key.

  async getMetadataValues(key: string) {
    return this.request(`/metadata/values/${encodeURIComponent(key)}`);
  }

• src/index.ts:526-528 (handler)

  Dispatch logic in the MCP server's CallToolRequest handler that routes calls to 'get_metadata_values' to the client implementation.

  case "get_metadata_values":
    result = await this.client.getMetadataValues(args?.key as string);
    break;

• src/index.ts:428-438 (schema)

  Input schema definition and tool registration for 'get_metadata_values' in the ListToolsRequest response.

  {
    name: "get_metadata_values",
    description: "Get all unique values for a specific frontmatter key",
    inputSchema: {
      type: "object",
      properties: {
        key: { type: "string", description: "Frontmatter key" },
      },
      required: ["key"],
    },
  },

• src/index.ts:272-440 (registration)

  Registration of all tools including get_metadata_values via the ListToolsRequest handler in setupTools method.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      // Directory Operations
      {
        name: "list_directory",
        description: "List directory contents with pagination to prevent context overflow. Shows immediate contents by default.",
        inputSchema: {
          type: "object",
          properties: {
            path: { type: "string", description: "Directory path to list", default: "." },
            recursive: { type: "boolean", description: "Include subdirectories recursively", default: false },
            limit: { type: "number", description: "Maximum items to return", default: 50 },
            offset: { type: "number", description: "Pagination offset", default: 0 },
          },
        },
      },
  
      // File Operations
      {
        name: "read_file",
        description: "Read content of a specific file from the vault",
        inputSchema: {
          type: "object",
          properties: {
            path: { type: "string", description: "Path to the file" },
          },
          required: ["path"],
        },
      },
      {
        name: "write_file",
        description: "Write file content with different modes: overwrite (default), append, or prepend. Handles both create and update operations.",
        inputSchema: {
          type: "object",
          properties: {
            path: { type: "string", description: "Path to the file" },
            content: { type: "string", description: "Content to write" },
            mode: { type: "string", enum: ["overwrite", "append", "prepend"], description: "Write mode", default: "overwrite" },
          },
          required: ["path", "content"],
        },
      },
      {
        name: "delete_item",
        description: "Delete a file or directory from the vault",
        inputSchema: {
          type: "object",
          properties: {
            path: { type: "string", description: "Path to the item to delete" },
          },
          required: ["path"],
        },
      },
  
      // AI-Native Note Operations
      {
        name: "create_or_update_note",
        description: "Create or update a note with content and frontmatter. Performs upsert operation - creates if doesn't exist, updates if it does.",
        inputSchema: {
          type: "object",
          properties: {
            path: { type: "string", description: "Path for the note (without .md extension)" },
            content: { type: "string", description: "Note content" },
            frontmatter: { type: "object", description: "Frontmatter metadata", default: {} },
          },
          required: ["path", "content"],
        },
      },
      {
        name: "get_daily_note",
        description: "Get daily note for a specific date. Handles common daily note naming conventions and file locations.",
        inputSchema: {
          type: "object",
          properties: {
            date: { type: "string", description: "Date (today, yesterday, tomorrow, or YYYY-MM-DD)", default: "today" },
          },
        },
      },
      {
        name: "get_recent_notes",
        description: "Get recently modified notes, ordered by modification time",
        inputSchema: {
          type: "object",
          properties: {
            limit: { type: "number", description: "Number of recent notes to return", default: 5 },
          },
        },
      },
  
      // Enhanced Search and Discovery
      {
        name: "search_vault",
        description: "Search vault content across files, filenames, and metadata with advanced filtering",
        inputSchema: {
          type: "object",
          properties: {
            query: { type: "string", description: "Search query" },
            scope: {
              type: "array",
              items: { type: "string", enum: ["content", "filename", "tags"] },
              description: "Search scope - where to look for the query",
              default: ["content", "filename", "tags"]
            },
            path_filter: { type: "string", description: "Limit search to specific path prefix" },
          },
          required: ["query"],
        },
      },
      {
        name: "find_related_notes",
        description: "Find notes related to a given note based on shared tags, links, or backlinks",
        inputSchema: {
          type: "object",
          properties: {
            path: { type: "string", description: "Path to the source note" },
            on: {
              type: "array",
              items: { type: "string", enum: ["tags", "links"] },
              description: "Relationship criteria to use for finding related notes",
              default: ["tags", "links"]
            },
          },
          required: ["path"],
        },
      },
  
      // Legacy Tools (for backward compatibility)
      {
        name: "get_note",
        description: "Get a specific note with its content and metadata (legacy)",
        inputSchema: {
          type: "object",
          properties: {
            path: { type: "string", description: "Path to the note" },
          },
          required: ["path"],
        },
      },
      {
        name: "list_notes",
        description: "List all notes in the vault with optional search filter (legacy with search support)",
        inputSchema: {
          type: "object",
          properties: {
            search: { type: "string", description: "Optional search query to filter notes" },
          },
        },
      },
      {
        name: "get_metadata_keys",
        description: "Get all available frontmatter keys from notes",
        inputSchema: {
          type: "object",
          properties: {},
        },
      },
      {
        name: "get_metadata_values",
        description: "Get all unique values for a specific frontmatter key",
        inputSchema: {
          type: "object",
          properties: {
            key: { type: "string", description: "Frontmatter key" },
          },
          required: ["key"],
        },
      },
    ],
  }));