macOS MCP Servers for Claude Desktop

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.

Overview

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

🚀 NEW: GitHub Copilot Integration

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.

Prerequisites

• macOS (tested on macOS 13+)
• Node.js 18+
• Claude Desktop app
• AppleScript permissions for the applications you want to control

Installation

For Claude Desktop

1. Clone the repository:

   git clone <repository-url>
   cd project-2
   

2. Install dependencies:

   npm install
   

3. Build the TypeScript code:

   npm run build
   

4. Configure 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.json
   

   Or manually add the server configurations to your existing Claude Desktop config file.

For GitHub Copilot (VS Code)

1. Complete the Claude Desktop installation steps above first

2. Install the VS Code extension:

   cd vscode-extension
   npm install
   npm run compile
   

3. Install 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.vsix
   

4. Configure 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

5. 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.

Configuration

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
  }
}

Available Tools

Spotify MCP Server

• 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

Apple Music MCP Server

• 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

Notes MCP Server

• 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

Calendar MCP Server

• 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

FaceTime MCP Server

• 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

Contacts MCP Server

• 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

Usage Examples

Claude Desktop

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"

GitHub Copilot in VS Code

With the VS Code extension installed, you can use GitHub Copilot Chat with the @macos-mcp participant:

Chat Commands

• @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

Command Palette

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

Example Conversations

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)

Development

Building the VS Code Extension

cd vscode-extension
npm run compile

Packaging the Extension

cd vscode-extension
npm install -g vsce
vsce package

Testing Individual Servers

You can test each server individually:

# Test Spotify server
node dist/spotify/index.js

# Test Notes server  
node dist/notes/index.js

Adding New Features

Each server follows the same pattern:

1. Define Zod schemas for input validation
2. Implement tool handlers using AppleScript
3. Register tools with the MCP server
4. Handle errors gracefully

Troubleshooting

Common Issues

1. Permission Denied Errors

   • Ensure you've granted the necessary permissions in System Preferences
   • Try running the failing operation manually first

2. App Not Found Errors

   • Make sure the target application is installed
   • Verify the application name in the AppleScript

3. 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

4. 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

5. 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)

6. Build Errors

   • Run npm install to ensure all dependencies are installed
   • Check TypeScript compilation with npm run build

Debug Mode

For debugging Claude Desktop servers, you can run servers with additional logging:

DEBUG=* node dist/spotify/index.js

For debugging the VS Code extension:

1. Open the extension development host (F5 in the extension folder)
2. Check the Output panel for "macOS MCP Servers" logs
3. Use Developer Tools (Help > Toggle Developer Tools) for detailed debugging

Security Considerations

• 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

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly on macOS
5. Submit a pull request

License

This project is provided as-is for educational and personal use. Please respect the terms of service of the applications you're integrating with.

Support

If you encounter issues:

1. Check the troubleshooting section above
2. Verify your macOS permissions
3. Ensure all applications are properly installed
4. 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.