Enables interaction with native Apple applications including Notes, Calendar, FaceTime, and Contacts through AppleScript automation
Provides comprehensive control over Apple Music including playback control, library search, playlist management, and library statistics
Integrates with GitHub Copilot Chat in VS Code to control macOS applications through natural language commands and chat participants
Bridges Claude Desktop with native macOS applications using AppleScript to control system functions and native app interactions
Offers complete Spotify control including playback management, track search, playlist operations, volume control, and playback mode toggles
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@macOS MCP Servers play my 'Workout Mix' playlist on Spotify"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A collection of Model Context Protocol (MCP) servers that enable Claude Desktop to interact with native macOS applications including Spotify, Apple Music, Notes, Calendar, FaceTime, and Contacts.
This project provides 6 MCP servers that bridge the gap between Claude Desktop and your macOS native applications, with full GitHub Copilot integration for VS Code users:
Spotify MCP Server: Control Spotify playback, search tracks, manage playlists
Apple Music MCP Server: Control Apple Music, browse library, manage playlists
Notes MCP Server: Create, read, search, and manage Apple Notes
Calendar MCP Server: View and create calendar events, manage schedules
FaceTime MCP Server: Initiate video/audio calls, manage call settings
Contacts MCP Server: Search, create, update, and manage contacts
In addition to Claude Desktop, you can now use these servers directly in VS Code through GitHub Copilot Chat! Ask Copilot to control your macOS apps using natural language.
Related MCP server: Music MCP
macOS (tested on macOS 13+)
Node.js 18+
Claude Desktop app
AppleScript permissions for the applications you want to control
Clone the repository:
git clone <repository-url>
cd project-2Install dependencies:
npm installBuild the TypeScript code:
npm run buildConfigure Claude Desktop:
Copy the provided claude_desktop_config.json to your Claude Desktop configuration directory:
# On macOS, the config file should be placed at:
cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.jsonOr manually add the server configurations to your existing Claude Desktop config file.
Complete the Claude Desktop installation steps above first
Install the VS Code extension:
cd vscode-extension
npm install
npm run compileInstall the extension in VS Code:
# Package the extension (run from vscode-extension directory)
cd vscode-extension
npx vsce package
# Install in VS Code
code --install-extension macos-mcp-servers-vscode-1.0.0.vsixConfigure the extension:
Open VS Code settings (Cmd+,)
Search for "macOS MCP"
Set the project path to your compiled dist directory (e.g., /path/to/project-2/dist)
Or enable auto-detection if the project is in your workspace
Grant necessary permissions:
When you first use each server, macOS will prompt you to grant permissions for:
System Events (for keyboard shortcuts)
Individual apps (Spotify, Music, Notes, Calendar, FaceTime, Contacts)
Grant these permissions in System Preferences > Security & Privacy > Privacy.
The claude_desktop_config.json file contains the configuration for all 6 MCP servers. Make sure the paths point to your built JavaScript files:
{
"mcpServers": {
"spotify-mcp-server": {
"command": "node",
"args": ["/absolute/path/to/project-2/dist/spotify/index.js"]
},
// ... other servers
}
}get_current_track - Get information about the currently playing track
play_pause - Toggle play/pause
next_track / previous_track - Skip tracks
set_volume - Control volume (0-100)
search_tracks - Search for tracks
get_playlists - List user playlists
play_playlist - Play a specific playlist
toggle_shuffle / toggle_repeat - Control playback modes
set_position - Seek to specific position in track
get_current_track - Get currently playing song info
play_pause - Toggle playback
next_track / previous_track - Skip tracks
set_volume - Control volume
search_library - Search Apple Music library
search_artist - Find artists
get_playlists - List playlists
play_playlist - Play specific playlist
toggle_shuffle / toggle_repeat - Playback controls
get_library_stats - Get library statistics
create_note - Create new note with title and content
get_note - Retrieve specific note by title
search_notes - Search notes by content or title
update_note - Modify existing note content
delete_note - Remove a note
list_notes - Get all notes with basic info
get_folders - List note folders
create_folder - Create new note folder
get_today_events - Show today's calendar events
get_upcoming_events - Show future events (next 7 days)
create_event - Create new calendar event
search_events - Find events by title or content
get_event_details - Get detailed event information
list_calendars - Show available calendars
get_events_for_date - Get events for specific date
start_facetime_call - Start video call with contact
start_facetime_audio_call - Start audio-only call
check_facetime_status - Check FaceTime availability
end_current_call - End active call
toggle_mute - Mute/unmute microphone
toggle_video - Turn camera on/off
search_contacts - Find contacts by name, email, or phone
get_contact_details - Get full contact information
create_contact - Add new contact
update_contact - Modify contact information
delete_contact - Remove contact
get_all_contacts - List all contacts (limited to 50)
get_contact_groups - Show contact groups
get_recent_contacts - Show recently added contacts
Once configured, you can interact with your macOS apps through Claude Desktop:
"Play my workout playlist on Spotify"
"Create a note about today's meeting"
"What's on my calendar for tomorrow?"
"Start a FaceTime call with John"
"Find all contacts from Apple Inc"
"Pause the music and turn up the volume"
With the VS Code extension installed, you can use GitHub Copilot Chat with the @macos-mcp participant:
@macos-mcp play my favorite playlist on Spotify
@macos-mcp create a note called "Meeting Notes"
@macos-mcp what's on my calendar today?
@macos-mcp call mom on FaceTime
@macos-mcp search contacts for John
@macos-mcp pause the music
You can also use VS Code's Command Palette (Cmd+Shift+P) to access quick actions:
macOS MCP: Get Current Spotify Track
macOS MCP: Spotify Play/Pause
macOS MCP: Create Apple Note
macOS MCP: Get Today's Calendar Events
macOS MCP: Search Contacts
macOS MCP: Start FaceTime Call
Music Control:
You: @macos-mcp what's currently playing on Spotify?
Copilot: 🎵 Current Track: "Bohemian Rhapsody" by Queen (4:32 remaining)
You: @macos-mcp pause it and set volume to 50
Copilot: 🎵 Paused playback
🔊 Volume set to 50%Notes and Calendar:
You: @macos-mcp create a note about the team meeting and check my calendar
Copilot: 📝 Created note: "Team Meeting Notes"
📅 Today's Events: Daily Standup (10:00 AM), Team Meeting (2:00 PM)cd vscode-extension
npm run compilecd vscode-extension
npm install -g vsce
vsce packageYou can test each server individually:
# Test Spotify server
node dist/spotify/index.js
# Test Notes server
node dist/notes/index.jsEach server follows the same pattern:
Define Zod schemas for input validation
Implement tool handlers using AppleScript
Register tools with the MCP server
Handle errors gracefully
Permission Denied Errors
Ensure you've granted the necessary permissions in System Preferences
Try running the failing operation manually first
App Not Found Errors
Make sure the target application is installed
Verify the application name in the AppleScript
Claude Desktop Not Recognizing Servers
Check that the config file is in the correct location
Verify all file paths are absolute and correct
Restart Claude Desktop after configuration changes
VS Code Extension Not Working
Ensure the extension is properly installed and activated
Check the project path in extension settings
Verify the MCP servers are built in the dist directory
Restart VS Code after configuration changes
GitHub Copilot Chat Participant Not Available
Make sure you have GitHub Copilot subscription
Verify the extension is activated (check Extensions view)
Try reloading the VS Code window (Cmd+R)
Build Errors
Run npm install to ensure all dependencies are installed
Check TypeScript compilation with npm run build
For debugging Claude Desktop servers, you can run servers with additional logging:
DEBUG=* node dist/spotify/index.jsFor debugging the VS Code extension:
Open the extension development host (F5 in the extension folder)
Check the Output panel for "macOS MCP Servers" logs
Use Developer Tools (Help > Toggle Developer Tools) for detailed debugging
These servers use AppleScript to control macOS applications
All operations require explicit user permission grants
No sensitive data is stored or transmitted
All interactions are local to your machine
Fork the repository
Create a feature branch
Make your changes
Test thoroughly on macOS
Submit a pull request
This project is provided as-is for educational and personal use. Please respect the terms of service of the applications you're integrating with.
If you encounter issues:
Check the troubleshooting section above
Verify your macOS permissions
Ensure all applications are properly installed
Check Claude Desktop logs for error details
Note: This project requires macOS and uses AppleScript for native app integration. It will not work on other operating systems.
Create a new folder in Apple Notes
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the folder to create |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool creates a folder, implying a write operation, but lacks details on permissions, error handling, whether the folder name must be unique, or what happens on success/failure. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks critical context such as return values, error conditions, or behavioral nuances (e.g., folder naming rules). Given the complexity of a create operation, this leaves significant gaps for an AI agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'name' parameter fully documented in the schema. The description does not add any additional meaning or context beyond what the schema provides, such as naming constraints or examples. Given the high schema coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 folder') and the target resource ('in Apple Notes'), which is specific and unambiguous. However, it does not explicitly differentiate this tool from its sibling 'list_folders', which handles reading rather than creating folders, leaving room for slight improvement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., permissions), when not to use it, or how it relates to siblings like 'list_folders' for checking existing folders, which is a significant gap for effective tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new note in Apple Notes
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Content/body of the note | |
| folder | No | Folder name to store the note (optional) | |
| title | Yes | Title of the note |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool creates a note but doesn't mention what happens on success (e.g., returns a note ID), potential errors (e.g., invalid folder), or side effects (e.g., note becomes immediately accessible). This leaves significant gaps 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any fluff. It's appropriately sized and front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, how errors are handled, or important behavioral details like whether the 'folder' parameter must reference an existing folder. This leaves the agent with insufficient context for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds no additional meaning about parameters beyond implying creation, which is redundant with the tool name. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('a new note in Apple Notes'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'update_note' or 'get_note' beyond the basic verb, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'update_note' or 'search_notes'. It lacks any context about prerequisites, such as needing an existing folder for the optional 'folder' parameter, or when creation might fail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a note by title
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Title of the note to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool deletes a note, implying a destructive mutation, but does not describe consequences (e.g., irreversible deletion, no confirmation prompt), permissions required, error handling, or what happens on success/failure. This is a significant gap for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It is appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and lack of annotations or output schema, the description is incomplete. It does not address critical context such as the permanence of deletion, error scenarios (e.g., if the note doesn't exist), or return values, leaving the agent with insufficient information for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the parameter 'title' fully documented in the schema. The description adds no additional meaning beyond what the schema provides (e.g., it does not explain title uniqueness, case sensitivity, or format constraints). Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Delete') and resource ('a note'), specifying the action and target. It distinguishes from siblings like 'create_note' or 'update_note' by focusing on deletion, but does not explicitly differentiate from other destructive operations or note-related tools beyond the verb itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., the note must exist), exclusions (e.g., cannot delete protected notes), or suggest alternatives like 'update_note' for modification instead of deletion, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the content of a specific note by title
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Title of the note to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Get' implies a read operation, it doesn't address important aspects like error handling (what happens if the note doesn't exist), authentication requirements, rate limits, or what format the content returns in. The description is minimal and lacks behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just one sentence with no wasted words. It's front-loaded with the core purpose and efficiently communicates the basic functionality without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a retrieval tool with no annotations and no output schema, the description is insufficient. It doesn't explain what format the note content returns in, how errors are handled, or any prerequisites for successful execution. Given the lack of structured data, the description should provide more complete context about the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, with the single parameter 'title' clearly documented. The description adds no additional parameter semantics beyond what the schema already provides ('Title of the note to retrieve'), so it meets the baseline for high schema coverage without adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('content of a specific note'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'list_notes' or 'search_notes' beyond the basic retrieval concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'list_notes' or 'search_notes'. It mentions retrieving by title but doesn't specify if this is the only retrieval method or when title-based lookup is appropriate versus other approaches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of all note folders
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool retrieves a list but doesn't describe return format, pagination, sorting, permissions required, or error conditions. For a read operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It's appropriately sized for a simple tool and front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool with no output schema, the description is minimally adequate. It states what the tool does but lacks details on return format, permissions, or behavioral traits. Given the simplicity of the tool, it's complete enough to understand the basic function but leaves gaps in practical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100%, so there's no need for parameter documentation in the description. The description correctly doesn't mention any parameters, which is appropriate. A baseline of 4 is given since no parameters exist to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get a list') and resource ('all note folders'), making the purpose immediately understandable. It distinguishes from siblings like 'list_notes' by specifying folders rather than notes. However, it doesn't specify whether this includes all folders globally or within a specific scope, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_notes' or 'list_notes'. It doesn't mention prerequisites, context, or any exclusions. The agent must infer usage solely from the tool name and description without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of all notes
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits such as whether this is a read-only operation, if it requires authentication, rate limits, pagination, or what the return format looks like. This leaves significant gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded and appropriately sized for a simple tool, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters) but lack of annotations and output schema, the description is incomplete. It doesn't explain what 'list' entails (e.g., format, ordering, limits) or behavioral aspects, leaving the agent with insufficient context for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description doesn't add param info, but that's acceptable here, resulting in a baseline score above minimum viable due to the lack of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get a list') and resource ('all notes'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'search_notes' or 'list_folders', which would require mentioning scope or filtering capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'search_notes' (for filtered searches) or 'get_note' (for single notes). The description lacks context about use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for notes containing specific text
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query to find notes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool searches for notes, but doesn't describe key traits like whether it's read-only, how results are returned (e.g., pagination, sorting), error conditions, or performance characteristics. This leaves significant gaps for a search operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action, making it easy to parse, and every part of the sentence contributes to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a search tool with no annotations and no output schema, the description is incomplete. It lacks details on behavior (e.g., result format, limitations), usage context, and how it differs from siblings, making it inadequate for an agent to reliably invoke this tool without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the parameter 'query' fully documented in the schema. The description adds no additional meaning beyond implying text-based search, which aligns with the schema but doesn't provide extra context like query syntax or examples. Baseline 3 is appropriate as the schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search for notes') and the target resource ('notes'), specifying the operation as finding notes containing specific text. It distinguishes from siblings like 'list_notes' by implying text-based filtering, but doesn't explicitly differentiate it from other search-related tools (none present in siblings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'list_notes' or 'get_note'. The description implies it's for text-based searches, but doesn't specify scenarios, prerequisites, or exclusions, leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the content of an existing note
| Name | Required | Description | Default |
|---|---|---|---|
| newContent | Yes | New content for the note | |
| title | Yes | Title of the note to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool updates content, implying a mutation, but fails to describe critical traits: whether it requires specific permissions, if changes are reversible, what happens on failure (e.g., invalid title), or the response format. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It is front-loaded with the core action ('Update'), making it easy to parse. Every part of the sentence earns its place by specifying the resource and scope, achieving optimal conciseness for a basic tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a mutation with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., error handling, permissions), output expectations, and usage context relative to siblings. While the schema covers parameters well, the overall context for safe and effective use by an agent is insufficient, especially for a write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with clear descriptions for both parameters ('title' and 'newContent'), so the schema does the heavy lifting. The description adds minimal value by implying 'newContent' replaces existing content, but doesn't elaborate on parameter interactions (e.g., if 'title' is used to identify the note) or constraints beyond what the schema provides. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('content of an existing note'), making the purpose immediately understandable. It distinguishes from siblings like 'create_note' (new vs. existing) and 'delete_note' (modify vs. remove). However, it doesn't specify what aspects of the note are updated beyond 'content' (e.g., title or metadata), which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., the note must exist), exclusions (e.g., cannot update non-existent notes), or comparisons to siblings like 'create_note' for new notes or 'get_note' for viewing. This lack of contextual direction leaves the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0create_foldercreate_notedelete_noteget_notelist_folderslist_notessearch_notesupdate_noteScored across 8 tools
Every tool has a clearly distinct purpose with no ambiguity. Each targets a specific action on a specific resource (e.g., create_folder vs. create_note, get_note vs. list_notes vs. search_notes), making it easy for an agent to select the right tool.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., create_folder, list_notes, update_note). This predictability enhances usability and reduces confusion for agents.
With 8 tools, the server is well-scoped for managing Apple Notes. Each tool earns its place by covering essential CRUD operations and utilities like searching, without being too sparse or bloated.
The tool surface provides complete CRUD/lifecycle coverage for Apple Notes, including create, read, update, delete, list, and search operations for both notes and folders. There are no obvious gaps that would cause agent failures.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.
Connects ChatGPT to your Apple Calendar via a local Mac agent + Vercel relay
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
