Building a Notes MCP Server

In this guide, you’ll learn how to build a complete MCP (Model Context Protocol) server from scratch. This server will manage a collection of markdown notes and has these features:

List and Read Notes: Allow clients to browse and view markdown files stored on the server
Write Notes: Provide a tool for creating or updating notes
Offer Smart Prompts: Generate contextual prompts, like creating a daily note template or summarizing existing content

Prerequisites

Node.js v20.0 or later installed
An API key from a supported Model Provider
An existing Mastra project (Follow the installation guide to set up a new project)

Adding necessary dependencies & files

Before you can create an MCP server you first need to install additional dependencies and set up a boilerplate folder structure.

Install `@mastra/mcp`

Add @mastra/mcp to your project:


npm install @mastra/mcp

Clean up the default project

After following the default installation guide your project will include files that are not relevant for this guide. You can safely remove them:


rm -rf src/mastra/agents src/mastra/workflows src/mastra/tools/weather-tool.ts

You should also change the src/mastra/index.ts file like so:

src/mastra/index.ts


import { Mastra } from "@mastra/core/mastra";
import { PinoLogger } from "@mastra/loggers";
import { LibSQLStore } from "@mastra/libsql";
 
export const mastra = new Mastra({
  storage: new LibSQLStore({
    // stores telemetry, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db
    url: ":memory:",
  }),
  logger: new PinoLogger({
    name: "Mastra",
    level: "info",
  }),
});

Set Up the Directory Structure

Create a dedicated directory for your MCP server’s logic and a notes directory for your notes:


mkdir notes src/mastra/mcp

Create the following files:


touch src/mastra/mcp/{server,resources,prompts}.ts

server.ts: Will contain the main MCP server configuration
resources.ts: Will handle listing and reading note files
prompts.ts: Will contain the logic for the smart prompts

The resulting directory structure should look like this:

- - - index.ts
    - - server.ts
      - resources.ts
      - prompts.ts

Creating the MCP Server

Let’s add the MCP server!

Create and Register the MCP Server

In src/mastra/mcp/server.ts, define the MCP server instance:

src/mastra/mcp/server.ts


import { MCPServer } from "@mastra/mcp";
 
export const notes = new MCPServer({
  name: "notes",
  version: "0.1.0",
  tools: {},
});

Register this MCP server in your Mastra instance at src/mastra/index.ts. The key notes is the public identifier for your MCP server:

src/mastra/index.ts


import { Mastra } from "@mastra/core";
import { PinoLogger } from "@mastra/loggers";
import { LibSQLStore } from "@mastra/libsql";
import { notes } from "./mcp/server";
 
export const mastra = new Mastra({
  storage: new LibSQLStore({
    // stores telemetry, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db
    url: ":memory:",
  }),
  logger: new PinoLogger({
    name: "Mastra",
    level: "info",
  }),
  mcpServers: {
    notes,
  },
});

Implement and Register Resource Handlers

Resource handlers allow clients to discover and read the content your server manages. Implement handlers to work with markdown files in the notes directory. Add to the src/mastra/mcp/resources.ts file:

src/mastra/mcp/resources.ts


import fs from "fs/promises";
import path from "path";
import { fileURLToPath } from "url";
import type { MCPServerResources, Resource } from "@mastra/mcp";
 
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const NOTES_DIR = path.resolve(__dirname, "../../notes"); // relative to the default output directory
 
const listNoteFiles = async (): Promise<Resource[]> => {
  try {
    await fs.mkdir(NOTES_DIR, { recursive: true });
    const files = await fs.readdir(NOTES_DIR);
    return files
      .filter((file) => file.endsWith(".md"))
      .map((file) => {
        const title = file.replace(".md", "");
        return {
          uri: `notes://${title}`,
          name: title,
          description: `A note about ${title}`,
          mime_type: "text/markdown",
        };
      });
  } catch (error) {
    console.error("Error listing note resources:", error);
    return [];
  }
};
 
const readNoteFile = async (uri: string): Promise<string | null> => {
  const title = uri.replace("notes://", "");
  const notePath = path.join(NOTES_DIR, `${title}.md`);
  try {
    return await fs.readFile(notePath, "utf-8");
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
      console.error(`Error reading resource ${uri}:`, error);
    }
    return null;
  }
};
 
export const resourceHandlers: MCPServerResources = {
  listResources: listNoteFiles,
  getResourceContent: async ({ uri }: { uri: string }) => {
    const content = await readNoteFile(uri);
    if (content === null) return { text: "" };
    return { text: content };
  },
};

src/mastra/mcp/server.ts


import { MCPServer } from "@mastra/mcp";
import { resourceHandlers } from "./resources";
 
export const notes = new MCPServer({
  name: "notes",
  version: "0.1.0",
  tools: {},
  resources: resourceHandlers,
});

Implement and Register a Tool

Tools are the actions your server can perform. Let’s create a write tool. First, define the tool in src/mastra/tools/write-note.ts:

src/mastra/tools/write-note.ts


import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { fileURLToPath } from "url";
import path from "node:path";
import fs from "fs/promises";
 
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const NOTES_DIR = path.resolve(__dirname, "../../../notes");
 
export const writeNoteTool = createTool({
  id: "write",
  description: "Write a new note or overwrite an existing one.",
  inputSchema: z.object({
    title: z
      .string()
      .nonempty()
      .describe("The title of the note. This will be the filename."),
    content: z
      .string()
      .nonempty()
      .describe("The markdown content of the note."),
  }),
  outputSchema: z.string().nonempty(),
  execute: async ({ context }) => {
    try {
      const { title, content } = context;
      const filePath = path.join(NOTES_DIR, `${title}.md`);
      await fs.mkdir(NOTES_DIR, { recursive: true });
      await fs.writeFile(filePath, content, "utf-8");
      return `Successfully wrote to note \"${title}\".`;
    } catch (error: any) {
      return `Error writing note: ${error.message}`;
    }
  },
});

src/mastra/mcp/server.ts


import { MCPServer } from "@mastra/mcp";
import { resourceHandlers } from "./resources";
import { writeNoteTool } from "../tools/write-note";
 
export const notes = new MCPServer({
  name: "notes",
  version: "0.1.0",
  resources: resourceHandlers,
  tools: {
    write: writeNoteTool,
  },
});

Implement and Register Prompts

Prompt handlers provide ready-to-use prompts for clients. You’ll add these three:

Daily note
Summarize a note
Brainstorm ideas

This requires a few markdown-parsing libraries you need to install:


npm install unified remark-parse gray-matter @types/unist

Implement the prompts in src/mastra/mcp/prompts.ts:

src/mastra/mcp/prompts.ts


import type { MCPServerPrompts } from "@mastra/mcp";
import { unified } from "unified";
import remarkParse from "remark-parse";
import matter from "gray-matter";
import type { Node } from "unist";
 
const prompts = [
  {
    name: "new_daily_note",
    description: "Create a new daily note.",
    version: "1.0.0",
  },
  {
    name: "summarize_note",
    description: "Give me a TL;DR of the note.",
    version: "1.0.0",
  },
  {
    name: "brainstorm_ideas",
    description: "Brainstorm new ideas based on a note.",
    version: "1.0.0",
  },
];
 
function stringifyNode(node: Node): string {
  if ("value" in node && typeof node.value === "string") return node.value;
  if ("children" in node && Array.isArray(node.children))
    return node.children.map(stringifyNode).join("");
  return "";
}
 
export async function analyzeMarkdown(md: string) {
  const { content } = matter(md);
  const tree = unified().use(remarkParse).parse(content);
  const headings: string[] = [];
  const wordCounts: Record<string, number> = {};
  let currentHeading = "untitled";
  wordCounts[currentHeading] = 0;
  tree.children.forEach((node) => {
    if (node.type === "heading" && node.depth === 2) {
      currentHeading = stringifyNode(node);
      headings.push(currentHeading);
      wordCounts[currentHeading] = 0;
    } else {
      const textContent = stringifyNode(node);
      if (textContent.trim()) {
        wordCounts[currentHeading] =
          (wordCounts[currentHeading] || 0) + textContent.split(/\\s+/).length;
      }
    }
  });
  return { headings, wordCounts };
}
 
const getPromptMessages: MCPServerPrompts["getPromptMessages"] = async ({
  name,
  args,
}) => {
  switch (name) {
    case "new_daily_note":
      const today = new Date().toISOString().split("T")[0];
      return [
        {
          role: "user",
          content: {
            type: "text",
            text: `Create a new note titled \"${today}\" with sections: \"## Tasks\", \"## Meetings\", \"## Notes\".`,
          },
        },
      ];
    case "summarize_note":
      if (!args?.noteContent) throw new Error("No content provided");
      const metaSum = await analyzeMarkdown(args.noteContent as string);
      return [
        {
          role: "user",
          content: {
            type: "text",
            text: `Summarize each section in ≤ 3 bullets.\\n\\n### Outline\\n${metaSum.headings.map((h) => `- ${h} (${metaSum.wordCounts[h] || 0} words)`).join("\\n")}`.trim(),
          },
        },
      ];
    case "brainstorm_ideas":
      if (!args?.noteContent) throw new Error("No content provided");
      const metaBrain = await analyzeMarkdown(args.noteContent as string);
      return [
        {
          role: "user",
          content: {
            type: "text",
            text: `Brainstorm 3 ideas for underdeveloped sections below ${args?.topic ? `on ${args.topic}` : "."}\\n\\nUnderdeveloped sections:\\n${metaBrain.headings.length ? metaBrain.headings.map((h) => `- ${h}`).join("\\n") : "- (none, pick any)"}`,
          },
        },
      ];
    default:
      throw new Error(`Prompt \"${name}\" not found`);
  }
};
 
export const promptHandlers: MCPServerPrompts = {
  listPrompts: async () => prompts,
  getPromptMessages,
};

src/mastra/mcp/server.ts


import { MCPServer } from "@mastra/mcp";
import { resourceHandlers } from "./resources";
import { writeNoteTool } from "../tools/write-note";
import { promptHandlers } from "./prompts";
 
export const notes = new MCPServer({
  name: "notes",
  version: "0.1.0",
  resources: resourceHandlers,
  prompts: promptHandlers,
  tools: {
    write: writeNoteTool,
  },
});

Run the Server

Great, you’ve authored your first MCP server! Now you can try it out by starting the playground:


npm run dev

Open http://localhost:4111 in your browser. In the left sidebar, select MCP Servers. Select the notes MCP server.

You’ll now be presented with instructions on how to add the MCP server to your IDE. You’re able to use this MCP server with any MCP Client. On the right side under Available Tools you can also select the write tool.

Inside the write tool, try it out by providing test as a name and this is a test for the markdown content. After clicking on Submit you’ll have a new test.md file inside notes.

Building a Notes MCP Server

Prerequisites

Adding necessary dependencies & files

Install @mastra/mcp

Clean up the default project

Set Up the Directory Structure

Creating the MCP Server

Create and Register the MCP Server

Implement and Register Resource Handlers

Implement and Register a Tool

Implement and Register Prompts

Run the Server

Install `@mastra/mcp`