# Directory Structure
```
├── .gitignore
├── bun.lockb
├── images
│ ├── demo.png
│ ├── desktop_settings.png
│ ├── logo.png
│ └── verify_installation.png
├── index.test.ts
├── index.ts
├── package.json
└── README.md
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
node_modules
dist
.DS_Store
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# MCP Apple Notes
A [Model Context Protocol (MCP)](https://www.anthropic.com/news/model-context-protocol) server that enables semantic search and RAG (Retrieval Augmented Generation) over your Apple Notes. This allows AI assistants like Claude to search and reference your Apple Notes during conversations.
## Features
- 🔍 Semantic search over Apple Notes using [`all-MiniLM-L6-v2`](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) on-device embeddings model
- 📝 Full-text search capabilities
- 📊 Vector storage using [LanceDB](https://lancedb.github.io/lancedb/)
- 🤖 MCP-compatible server for AI assistant integration
- 🍎 Native Apple Notes integration via JXA
- 🏃♂️ Fully local execution - no API keys needed
## Prerequisites
- [Bun](https://bun.sh/docs/installation)
- [Claude Desktop](https://claude.ai/download)
## Installation
1. Clone the repository:
```bash
git clone https://github.com/RafalWilinski/mcp-apple-notes
cd mcp-apple-notes
```
2. Install dependencies:
```bash
bun install
```
## Usage
1. Open Claude desktop app and go to Settings -> Developer -> Edit Config
2. Open the `claude_desktop_config.json` and add the following entry:
```json
{
"mcpServers": {
"local-machine": {
"command": "/Users/<YOUR_USER_NAME>/.bun/bin/bun",
"args": ["/Users/<YOUR_USER_NAME>/apple-notes-mcp/index.ts"]
}
}
}
```
Important: Replace `<YOUR_USER_NAME>` with your actual username.
3. Restart Claude desktop app. You should see this:
4. Start by indexing your notes. Ask Claude to index your notes by saying something like: "Index my notes" or "Index my Apple Notes".
## Troubleshooting
To see logs:
```bash
tail -n 50 -f ~/Library/Logs/Claude/mcp-server-local-machine.log
# or
tail -n 50 -f ~/Library/Logs/Claude/mcp.log
```
## Todos
- [ ] Apple notes are returned in the HTML format. We should turn them to Markdown and embed that
- [ ] Chunk source content using recursive text splitter or markdown text splitter
- [ ] Add an option to use custom embeddings model
- [ ] More control over DB - purge, custom queries, etc.
- [x] Storing notes in Notes via Claude
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "apple-notes-mcp",
"version": "1.0.0",
"author": "",
"type": "module",
"main": "index.ts",
"description": "",
"keywords": [],
"license": "ISC",
"scripts": {
"build": "bun build index.ts --outdir dist --target node",
"start": "bun index.ts",
"purge-db": "rm -rf ~/.mcp-apple-notes",
"test": "npx tsx index.test.ts"
},
"exports": {
".": "./index.ts"
},
"dependencies": {
"@ai-sdk/openai": "^1.0.8",
"@huggingface/transformers": "^3.1.2",
"@lancedb/lancedb": "^0.14.0",
"@langchain/textsplitters": "^0.1.0",
"@modelcontextprotocol/sdk": "^1.0.3",
"run-jxa": "^3.0.0",
"turndown": "^7.2.0",
"zod": "^3.24.1"
},
"devDependencies": {
"@types/turndown": "^5.0.5"
}
}
```
--------------------------------------------------------------------------------
/index.test.ts:
--------------------------------------------------------------------------------
```typescript
// Usage: npx tsx index.test.ts
import { test, describe } from "node:test";
import assert from "node:assert";
import * as lancedb from "@lancedb/lancedb";
import path from "node:path";
import os from "node:os";
import { LanceSchema } from "@lancedb/lancedb/embedding";
import { Utf8 } from "apache-arrow";
import {
createNotesTable,
indexNotes,
OnDeviceEmbeddingFunction,
searchAndCombineResults,
} from "./index";
describe("Apple Notes Indexing", async () => {
const db = await lancedb.connect(
path.join(os.homedir(), ".mcp-apple-notes", "data")
);
const func = new OnDeviceEmbeddingFunction();
const notesSchema = LanceSchema({
title: func.sourceField(new Utf8()),
content: func.sourceField(new Utf8()),
creation_date: func.sourceField(new Utf8()),
modification_date: func.sourceField(new Utf8()),
vector: func.vectorField(),
});
test("should create notes table", async () => {
const notesTable = await db.createEmptyTable("test-notes", notesSchema, {
mode: "create",
existOk: true,
});
assert.ok(notesTable, "Notes table should be created");
const count = await notesTable.countRows();
assert.ok(typeof count === "number", "Should be able to count rows");
});
test.skip("should index all notes correctly", async () => {
const { notesTable } = await createNotesTable("test-notes");
await indexNotes(notesTable);
const count = await notesTable.countRows();
assert.ok(typeof count === "number", "Should be able to count rows");
assert.ok(count > 0, "Should be able to count rows");
});
test("should perform vector search", async () => {
const start = performance.now();
const { notesTable } = await createNotesTable("test-notes");
const end = performance.now();
console.log(`Creating table took ${Math.round(end - start)}ms`);
await notesTable.add([
{
id: "1",
title: "Test Note",
content: "This is a test note content",
creation_date: new Date().toISOString(),
modification_date: new Date().toISOString(),
},
]);
const addEnd = performance.now();
console.log(`Adding notes took ${Math.round(addEnd - end)}ms`);
const results = await searchAndCombineResults(notesTable, "test note");
const combineEnd = performance.now();
console.log(`Combining results took ${Math.round(combineEnd - addEnd)}ms`);
assert.ok(results.length > 0, "Should return search results");
assert.equal(results[0].title, "Test Note", "Should find the test note");
});
test("should perform vector search on real indexed data", async () => {
const { notesTable } = await createNotesTable("test-notes");
const results = await searchAndCombineResults(notesTable, "15/12");
assert.ok(results.length > 0, "Should return search results");
assert.equal(results[0].title, "Test Note", "Should find the test note");
});
});
```
--------------------------------------------------------------------------------
/index.ts:
--------------------------------------------------------------------------------
```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
import * as lancedb from "@lancedb/lancedb";
import { runJxa } from "run-jxa";
import path from "node:path";
import os from "node:os";
import TurndownService from "turndown";
import {
EmbeddingFunction,
LanceSchema,
register,
} from "@lancedb/lancedb/embedding";
import { type Float, Float32, Utf8 } from "apache-arrow";
import { pipeline } from "@huggingface/transformers";
const { turndown } = new TurndownService();
const db = await lancedb.connect(
path.join(os.homedir(), ".mcp-apple-notes", "data")
);
const extractor = await pipeline(
"feature-extraction",
"Xenova/all-MiniLM-L6-v2"
);
@register("openai")
export class OnDeviceEmbeddingFunction extends EmbeddingFunction<string> {
toJSON(): object {
return {};
}
ndims() {
return 384;
}
embeddingDataType(): Float {
return new Float32();
}
async computeQueryEmbeddings(data: string) {
const output = await extractor(data, { pooling: "mean" });
return output.data as number[];
}
async computeSourceEmbeddings(data: string[]) {
return await Promise.all(
data.map(async (item) => {
const output = await extractor(item, { pooling: "mean" });
return output.data as number[];
})
);
}
}
const func = new OnDeviceEmbeddingFunction();
const notesTableSchema = LanceSchema({
title: func.sourceField(new Utf8()),
content: func.sourceField(new Utf8()),
creation_date: func.sourceField(new Utf8()),
modification_date: func.sourceField(new Utf8()),
vector: func.vectorField(),
});
const QueryNotesSchema = z.object({
query: z.string(),
});
const GetNoteSchema = z.object({
title: z.string(),
});
const server = new Server(
{
name: "my-apple-notes-mcp",
version: "1.0.0",
},
{
capabilities: {
tools: {},
},
}
);
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "list-notes",
description: "Lists just the titles of all my Apple Notes",
inputSchema: {
type: "object",
properties: {},
required: [],
},
},
{
name: "index-notes",
description:
"Index all my Apple Notes for Semantic Search. Please tell the user that the sync takes couple of seconds up to couple of minutes depending on how many notes you have.",
inputSchema: {
type: "object",
properties: {},
required: [],
},
},
{
name: "get-note",
description: "Get a note full content and details by title",
inputSchema: {
type: "object",
properties: {
title: z.string(),
},
required: ["title"],
},
},
{
name: "search-notes",
description: "Search for notes by title or content",
inputSchema: {
type: "object",
properties: {
query: z.string(),
},
required: ["query"],
},
},
{
name: "create-note",
description:
"Create a new Apple Note with specified title and content. Must be in HTML format WITHOUT newlines",
inputSchema: {
type: "object",
properties: {
title: { type: "string" },
content: { type: "string" },
},
required: ["title", "content"],
},
},
],
};
});
const getNotes = async () => {
const notes = await runJxa(`
const app = Application('Notes');
app.includeStandardAdditions = true;
const notes = Array.from(app.notes());
const titles = notes.map(note => note.properties().name);
return titles;
`);
return notes as string[];
};
const getNoteDetailsByTitle = async (title: string) => {
const note = await runJxa(
`const app = Application('Notes');
const title = "${title}"
try {
const note = app.notes.whose({name: title})[0];
const noteInfo = {
title: note.name(),
content: note.body(),
creation_date: note.creationDate().toLocaleString(),
modification_date: note.modificationDate().toLocaleString()
};
return JSON.stringify(noteInfo);
} catch (error) {
return "{}";
}`
);
return JSON.parse(note as string) as {
title: string;
content: string;
creation_date: string;
modification_date: string;
};
};
export const indexNotes = async (notesTable: any) => {
const start = performance.now();
let report = "";
const allNotes = (await getNotes()) || [];
const notesDetails = await Promise.all(
allNotes.map((note) => {
try {
return getNoteDetailsByTitle(note);
} catch (error) {
report += `Error getting note details for ${note}: ${error.message}\n`;
return {} as any;
}
})
);
const chunks = notesDetails
.filter((n) => n.title)
.map((node) => {
try {
return {
...node,
content: turndown(node.content || ""), // this sometimes fails
};
} catch (error) {
return node;
}
})
.map((note, index) => ({
id: index.toString(),
title: note.title,
content: note.content, // turndown(note.content || ""),
creation_date: note.creation_date,
modification_date: note.modification_date,
}));
await notesTable.add(chunks);
return {
chunks: chunks.length,
report,
allNotes: allNotes.length,
time: performance.now() - start,
};
};
export const createNotesTable = async (overrideName?: string) => {
const start = performance.now();
const notesTable = await db.createEmptyTable(
overrideName || "notes",
notesTableSchema,
{
mode: "create",
existOk: true,
}
);
const indices = await notesTable.listIndices();
if (!indices.find((index) => index.name === "content_idx")) {
await notesTable.createIndex("content", {
config: lancedb.Index.fts(),
replace: true,
});
}
return { notesTable, time: performance.now() - start };
};
const createNote = async (title: string, content: string) => {
// Escape special characters and convert newlines to \n
const escapedTitle = title.replace(/[\\'"]/g, "\\$&");
const escapedContent = content
.replace(/[\\'"]/g, "\\$&")
.replace(/\n/g, "\\n")
.replace(/\r/g, "");
await runJxa(`
const app = Application('Notes');
const note = app.make({new: 'note', withProperties: {
name: "${escapedTitle}",
body: "${escapedContent}"
}});
return true
`);
return true;
};
// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request, c) => {
const { notesTable } = await createNotesTable();
const { name, arguments: args } = request.params;
try {
if (name === "create-note") {
const { title, content } = CreateNoteSchema.parse(args);
await createNote(title, content);
return createTextResponse(`Created note "${title}" successfully.`);
} else if (name === "list-notes") {
return createTextResponse(
`There are ${await notesTable.countRows()} notes in your Apple Notes database.`
);
} else if (name == "get-note") {
try {
const { title } = GetNoteSchema.parse(args);
const note = await getNoteDetailsByTitle(title);
return createTextResponse(`${note}`);
} catch (error) {
return createTextResponse(error.message);
}
} else if (name === "index-notes") {
const { time, chunks, report, allNotes } = await indexNotes(notesTable);
return createTextResponse(
`Indexed ${chunks} notes chunks in ${time}ms. You can now search for them using the "search-notes" tool.`
);
} else if (name === "search-notes") {
const { query } = QueryNotesSchema.parse(args);
const combinedResults = await searchAndCombineResults(notesTable, query);
return createTextResponse(JSON.stringify(combinedResults));
} else {
throw new Error(`Unknown tool: ${name}`);
}
} catch (error) {
if (error instanceof z.ZodError) {
throw new Error(
`Invalid arguments: ${error.errors
.map((e) => `${e.path.join(".")}: ${e.message}`)
.join(", ")}`
);
}
throw error;
}
});
// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Local Machine MCP Server running on stdio");
const createTextResponse = (text: string) => ({
content: [{ type: "text", text }],
});
/**
* Search for notes by title or content using both vector and FTS search.
* The results are combined using RRF
*/
export const searchAndCombineResults = async (
notesTable: lancedb.Table,
query: string,
limit = 20
) => {
const [vectorResults, ftsSearchResults] = await Promise.all([
(async () => {
const results = await notesTable
.search(query, "vector")
.limit(limit)
.toArray();
return results;
})(),
(async () => {
const results = await notesTable
.search(query, "fts", "content")
.limit(limit)
.toArray();
return results;
})(),
]);
const k = 60;
const scores = new Map<string, number>();
const processResults = (results: any[], startRank: number) => {
results.forEach((result, idx) => {
const key = `${result.title}::${result.content}`;
const score = 1 / (k + startRank + idx);
scores.set(key, (scores.get(key) || 0) + score);
});
};
processResults(vectorResults, 0);
processResults(ftsSearchResults, 0);
const results = Array.from(scores.entries())
.sort(([, a], [, b]) => b - a)
.slice(0, limit)
.map(([key]) => {
const [title, content] = key.split("::");
return { title, content };
});
return results;
};
const CreateNoteSchema = z.object({
title: z.string(),
content: z.string(),
});
```