docs/src/content/en/guides/guide/notes-mcp-server.mdx
import Steps from "@site/src/components/Steps"; import StepItem from "@site/src/components/StepItem";
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:
v22.13.0 or later installedBefore you can create an MCP server you first need to install additional dependencies and set up a boilerplate folder structure.
<Steps> <StepItem> Add `@mastra/mcp` to your project:```bash npm2yarn
npm install @mastra/mcp@latest
```
```bash
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:
```ts title="src/mastra/index.ts"
import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'
import { LibSQLStore } from '@mastra/libsql'
export const mastra = new Mastra({
storage: new LibSQLStore({
id: 'mastra-storage',
// 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',
}),
})
```
```bash
mkdir notes src/mastra/mcp
```
Create the following files:
```bash
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:
```
<your-project-name>/
├── notes/
└── src/
└── mastra/
├── index.ts
├── mcp/
│ ├── server.ts
│ ├── resources.ts
│ └── prompts.ts
└── tools/
```
Let's add the MCP server!
<Steps> <StepItem> In `src/mastra/mcp/server.ts`, define the MCP server instance:```typescript title="src/mastra/mcp/server.ts"
import { MCPServer } from '@mastra/mcp'
export const notes = new MCPServer({
id: 'notes',
name: 'Notes Server',
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:
```typescript title="src/mastra/index.ts" {4, 15-17}
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({
id: 'mastra-storage',
// 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,
},
})
```
```typescript title="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 }
},
}
```
Register these resource handlers in `src/mastra/mcp/server.ts`:
```typescript title="src/mastra/mcp/server.ts" {2, 8}
import { MCPServer } from '@mastra/mcp'
import { resourceHandlers } from './resources'
export const notes = new MCPServer({
id: 'notes',
name: 'Notes Server',
version: '0.1.0',
tools: {},
resources: resourceHandlers,
})
```
```typescript title="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 inputData => {
try {
const { title, content } = inputData
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}`
}
},
})
```
Register this tool in `src/mastra/mcp/server.ts`:
```typescript title="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({
id: 'notes',
name: 'Notes Server',
version: '0.1.0',
resources: resourceHandlers,
tools: {
write: writeNoteTool,
},
})
```
- Daily note
- Summarize a note
- Brainstorm ideas
This requires a few markdown-parsing libraries you need to install:
```bash
npm install unified remark-parse gray-matter @types/unist
```
Implement the prompts in `src/mastra/mcp/prompts.ts`:
```typescript title="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,
}
```
Register these prompt handlers in `src/mastra/mcp/server.ts`:
```typescript title="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({
id: 'notes',
name: 'Notes Server',
version: '0.1.0',
resources: resourceHandlers,
prompts: promptHandlers,
tools: {
write: writeNoteTool,
},
})
```
Great, you've authored your first MCP server! Now you can try it out by starting the Mastra dev server and opening Studio:
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 selecting Submit you'll have a new test.md file inside notes.