Skip to main content
Glama
pongsapakl

mcp-inotes

by pongsapakl
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

mcp-inotes

Python License

A lightweight MCP (Model Context Protocol) server that enables Claude and other LLMs to interact with Apple Notes.

About

This MCP server gives Claude the ability to create, read, and append to notes in Apple Notes. It's designed with a safety-first approach: all operations are restricted to a single designated folder, and the server only supports append operations (no overwrites or deletions).

Perfect for using Claude as your AI journaling assistant, note-taking companion, or personal knowledge base manager.

Related MCP server: MCP Apple Notes

Features

  • Create new notes with title and body

  • Read existing notes by ID

  • Append content to notes (no overwrites)

  • List all notes with metadata

  • Safety-first: Operations restricted to "Claude Diary" folder only

  • Append-only design prevents accidental data loss

  • Built with FastMCP

Prerequisites

  • macOS - Uses AppleScript to interact with Notes.app

  • Python 3.12+

  • Apple Notes.app

  • Claude Desktop or another MCP-compatible client

  • Basic familiarity with MCP servers

Installation

git clone https://github.com/pongsapakl/mcp-inotes.git
cd mcp-inotes
uv sync

Configuration

Add to your MCP settings file. For Claude Desktop, edit:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Alternative: ~/.mcp.json

{
  "mcpServers": {
    "mcp-inotes": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-inotes",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}

Important: Replace /absolute/path/to/mcp-inotes with the actual path where you cloned this repository.

Required Setup

Before using the server, create a folder named "Claude Diary" in Apple Notes:

  1. Open Apple Notes

  2. Right-click in the sidebar

  3. Select "New Folder"

  4. Name it exactly: Claude Diary

This folder is where all notes will be created and managed.

Available Tools

  • create_note(title, body) - Create new note in Claude Diary folder

  • get_note(note_id) - Read full note content and metadata

  • append_to_note(note_id, content) - Append content to existing note (append-only)

  • get_notes_list() - List all notes with IDs and timestamps

Usage Examples

Here's how Claude can use these tools in practice:

Creating a daily journal entry:

User: "Create a journal entry for today about my morning routine"
Claude: [Uses create_note("Daily Journal - 2026-01-15", "Woke up at 7am...")]

Building on previous notes:

User: "Add my evening reflections to today's journal"
Claude: [Uses get_notes_list() to find today's note, then append_to_note()]

Searching through your notes:

User: "What did I write about my project last week?"
Claude: [Uses get_notes_list(), then get_note() to read relevant entries]

Safety & Constraints

This server is designed with deliberate limitations for safety:

Folder Restriction

  • All operations are hardcoded to work only with the "Claude Diary" folder

  • Cannot access, modify, or delete notes in other folders

  • Prevents accidental changes to important notes elsewhere in your Apple Notes

Append-Only Operations

  • No delete functionality

  • No overwrite functionality

  • Only supports creating new notes and appending to existing ones

  • Protects against accidental data loss

Why "Claude Diary"? The folder name is intentionally hardcoded rather than configurable. This constraint ensures you always know exactly where the MCP server can operate, reducing the risk of unintended modifications to other notes.

Limitations

  • Date filtering not implemented: The start_date and end_date parameters in get_notes_list() are accepted but not yet functional. Currently returns all notes from the Claude Diary folder.

  • macOS only: Relies on AppleScript, which is macOS-specific

  • Single folder: Cannot manage notes across multiple folders

  • No delete operations: By design, but means you'll need to manually clean up unwanted notes in Apple Notes

Troubleshooting

"Folder not found" error

  • Make sure you've created a folder named exactly "Claude Diary" in Apple Notes

  • The name is case-sensitive

Server not connecting

  • Verify the absolute path in your MCP config file is correct

  • Try running uv sync again to ensure dependencies are installed

  • Check Claude Desktop logs: ~/Library/Logs/Claude/

AppleScript permission denied

  • macOS may prompt you to grant permissions the first time

  • Check System Settings → Privacy & Security → Automation

  • Ensure Claude/your MCP client can control Apple Notes

Notes not appearing

  • Make sure you're looking in the "Claude Diary" folder in Apple Notes

  • Try refreshing the Notes app

  • Check that the note IDs being used are valid

Contributing

Contributions are welcome! Feel free to:

  • Report issues on GitHub

  • Submit pull requests for bug fixes or improvements

  • Suggest new features (while respecting the safety-first design philosophy)

License

MIT

Built with FastMCP | Learn more about Model Context Protocol

Available Tools

4 tools
append_to_noteA

Append content to an existing note (APPEND ONLY - no overwrite)

Args: note_id: The ID of the note to append to (x-coredata:// URL) content: The content to append

Returns: Success message

Note: This operation only APPENDS content. It cannot overwrite or delete existing content. This is a safety feature to prevent data loss.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYes
note_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and effectively discloses the append-only behavior, explicitly stating it cannot overwrite or delete, and framing it as a safety feature. This adds meaningful context beyond a simple verb phrase.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with Args, Returns, and a Note section, making it easy to scan. It is mostly concise, though the append-only emphasis is repeated, which is slightly redundant but reinforces the key safety trait.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with an output schema, the description is sufficiently complete. It covers the operation, parameters, return value, and a behavioral caveat. Minor gaps like error cases and formatting are not critical for such a straightforward tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description compensates by explaining note_id as 'the ID of the note to append to (x-coredata:// URL)' and content as 'the content to append'. This provides semantic meaning beyond the schema's plain string types, though more detail could be added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Append content to an existing note' with a specific verb and resource, and the 'APPEND ONLY - no overwrite' clarifier distinguishes it from sibling tools like create_note and get_note. The purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for adding content to an existing note, and the append-only constraint suggests a safe operation. However, it does not explicitly mention when to choose this tool over alternatives or provide exclusions, leaving the guidance implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_noteA

Create a new note in Claude Diary folder

Args: title: The title of the note body: The content/body of the note

Returns: Success message with note ID

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyYes
titleYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must fully disclose behavioral traits. It mentions the return value ('Success message with note ID') but does not disclose what happens if a note with the same title already exists, whether creation overwrites or errors, or any required permissions. This is a significant gap for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the core purpose. The Args section clearly maps each parameter, and the Returns section provides output expectations. Every sentence is useful, with no padding or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple create operation with two string parameters, the description adequately covers what the tool does, its parameters, and its return value. The presence of an output schema is noted but the description already includes the return info. Minor gaps like duplicate handling prevent a 5, but overall it is sufficiently complete for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides only type 'string' with no descriptions, so the description carries the burden. It clearly defines 'title' as the title and 'body' as the content/body, which adds meaning beyond the schema. It does not include potential constraints (e.g., max length), but the basics are well-covered.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Create a new note in Claude Diary folder'. The verb 'create' and resource 'note' are specific, and the phrase 'Claude Diary folder' adds context. This distinguishes it from sibling tools like append_to_note, which modifies an existing note, and get_note/get_notes_list, which retrieve notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly indicates when to use this tool ('Create a new note'), and the contrast with sibling names (append, get) implies it is for new records rather than modifications or reads. However, it does not explicitly mention alternatives or situations where other tools would be preferred, which would make it a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_noteA

Get full content of a specific note by ID

Args: note_id: The note ID (x-coredata:// URL)

Returns: Formatted note content with metadata

ParametersJSON Schema
NameRequiredDescriptionDefault
note_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the burden of explaining behavior. It only states that it returns formatted content with metadata, but doesn't disclose the read-only nature, error handling (e.g., missing ID), or any permissions/rate limits. The lack of such details makes it opaque for an unannotated tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with Args and Returns sections, providing exactly the needed detail without any fluff. Every sentence serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 1-parameter tool with an output schema, the description is nearly complete. It explains the input format and return type, though it omits potential error states or preconditions. Still, given its simplicity, it's adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning by specifying the format of note_id as an x-coredata:// URL, which is not present in the schema's type-only definition. This helps the agent construct the parameter correctly despite the schema being minimal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the full content of a specific note by ID, using a specific verb ('Get') and resource ('note by ID'). It distinguishes itself from siblings by focusing on reading a single note versus creating, appending, or listing notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when the user needs the complete content of one note, but it doesn't explicitly state when not to use it or mention alternatives. Since siblings are visible, the intended context is clear, but there's no direct comparison or exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_notes_listA

Get list of notes from Claude Diary folder

Args: start_date: Start date in ISO format (YYYY-MM-DD) - not yet implemented end_date: End date in ISO format (YYYY-MM-DD) - not yet implemented

Returns: Formatted list of notes with metadata

Note: Currently returns all notes from Claude Diary folder. Date filtering is not yet implemented.

ParametersJSON Schema
NameRequiredDescriptionDefault
end_dateNo
start_dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and discloses that date filtering is 'not yet implemented', that it 'currently returns all notes', and that the output is a 'formatted list of notes with metadata'. This gives important behavioral expectations beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with leading purpose, Args, Returns, and Note sections. Every line adds value, especially the note about unimplemented parameters, without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with an output schema, the description covers key aspects: what it lists, current behavior, and parameter status. It doesn't mention sorting or folder details, but these are not critical given the sibling context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description compensates by providing the ISO format for start_date and end_date and explicitly noting they are 'not yet implemented'. This adds meaning beyond the bare schema type and default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get list of notes from Claude Diary folder', specifying a concrete action and resource. It distinguishes from siblings like get_note (single note) and create_note, making the list-scope explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing notes but does not explicitly contrast with alternative tools. It doesn't state 'use this when you need all notes, use get_note for one note', leaving this to inference from sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedappend_to_note
    • First observedcreate_note
    • First observedget_note
    • First observedget_notes_list
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct purpose: create, append, retrieve single, and list. No overlap or ambiguity exists between the operations.

Naming Consistency5/5

All tool names follow the consistent verb_noun pattern (create_note, append_to_note, get_note, get_notes_list). The naming convention is uniform and predictable.

Tool Count5/5

With 4 tools, the server is well-scoped for a note-taking and diary management domain. Each tool serves a necessary function without redundancy.

Completeness4/5

The server covers create, append (update), read, and list operations, which covers the core lifecycle. Minor gaps include no delete functionality and date filtering not yet implemented, but these are not critical for the primary use case.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers