# Mcp Mac

> A Proof of Concept MCP server for macOS, enabling AI agents to interact with macOS apps

- **Type:** MCP server
- **Install:** `agentstack add mcp-samicokar-mcp-mac`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [samicokar](https://agentstack.voostack.com/s/samicokar)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [samicokar](https://github.com/samicokar)
- **Source:** https://github.com/samicokar/mcp-mac

## Install

```sh
agentstack add mcp-samicokar-mcp-mac
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-mac

**AI-powered automation of macOS Apple applications**

This is a proof of concept to learn about AI and MacOS, and developed using with AI. I am unlikely to progress this any further. 

mcp-mac enables AI agents to interact with macOS applications (Finder, Mail, Contacts, etc) using AppleScript through the Model Context Protocol (MCP). This allows AI assistants to perform tasks like searching contacts, managing files, and checking email on your behalf. 

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that allows AI applications to securely connect to external data sources and tools. mcp-mac implements an MCP server that provides AI agents with controlled access to your macOS applications.

## Current Status

### Available Tools
- **Finder**: Get selected files, get current folder location
- **Mail**: List accounts, get inbox unread/total count, create and send messages
- **Contacts**: Search people, get contact information
- **Reminders**: List lists, get incomplete reminders, create reminders
- **Notes**: List folders, search/get recent notes, create notes
- **TextEdit**: List documents, create documents
- **Calendar**: List calendars, get today's/upcoming events, create events
- **Workflow**: Composite tools for multi-app actions (e.g., Contacts to TextEdit)
- **Discovery**: Introspect application capabilities

## Quick Start

### Prerequisites
- macOS (tested on MacOS 26.2)
- Node.js 18

### Installation
```bash
# Clone the repository
git clone 
cd mcp-mac

# Install dependencies
npm install

# Build the project
npm run build
```

### E.g usage with Q CLI
```bash
# Add to your Q CLI MCP configuration
q config mcp add mcp-mac ./dist/index.js

# Use in Q chat sessions
# The tools will be available as mcp-mac___tool-name
```

## Example Workflow

Once set up, you can ask an AI assistant to:
> "Get John Smith's contact information and also check how many unread emails I have"

The AI will use the mcp-mac tools to:
1. Search for "John Smith" in Contacts
2. Retrieve his contact details
3. Check your Mail inbox count
4. Provide a combined response

## Project Structure

```
mcp-mac/
├── src/index.ts          # MCP server implementation
├── dist/                 # Compiled JavaScript
├── docs/                 # Project documentation
│   ├── PROJECT-CHARTER.md    # Project governance
│   ├── DEVELOPMENT-GUIDE.md  # Development processes
│   └── iterations/           # Implementation history
└── package.json          # Dependencies and scripts
```

## Documentation

- **[Architecture](docs/ARCHITECTURE.md)** - System design and technical details
- **[Technical Lessons](docs/LESSONS-LEARNED.md)** - AppleScript quirks and implementation details

## Privacy & Security

mcp-mac accesses your personal data (contacts, email, files) through standard macOS AppleScript interfaces. All data processing happens locally on your machine. No data is transmitted to external servers.

**Important**: Only use with trusted AI applications and review any automation requests before execution.

## Disclaimer

This software is provided "as is," without warranty of any kind, express or implied, including
but not limited to the warranties of merchantability, fitness for a particular purpose and
non-infringement. The entire risk as to the quality and performance of the program is with you.
In no event shall the author or copyright holders be liable for any claim, damages, or other
liability, whether in an action of contract, tort or otherwise, arising from, out of or in
connection with the software or the use or other dealings in the software. You assume all
responsibility for the use of this software on your system, and you are accountable for any
actions or consequences that arise from its use.

## License

Licensed under the MIT license.
[MIT](./LICENSE.md)

## Copyright

Copyright (c) Sami Cokar, 2025

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [samicokar](https://github.com/samicokar)
- **Source:** [samicokar/mcp-mac](https://github.com/samicokar/mcp-mac)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-samicokar-mcp-mac
- Seller: https://agentstack.voostack.com/s/samicokar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.