{
  "markdown": "# psyXe MCP Server\n\nAn [MCP server](https://modelcontextprotocol.io/) that gives AI assistants access to your Apple Notes, Reminders, and Contacts — with optional BERT-powered semantic search.\n\nAll tools run locally via macOS-native APIs (AppleScript, EventKit, Contacts framework). No data leaves your Mac. No API keys required.\n\n**New to MCP?** Check out the [FAQ](FAQ.md) for answers to common questions about what this is, whether it works with your setup, and how your data stays private.\n\n## Video Tutorials\n\n| | |\n|---|---|\n| [![Notes & Semantic Search](https://img.youtube.com/vi/Ha-O8jwoh9E/mqdefault.jpg)](https://youtu.be/Ha-O8jwoh9E) | [**Apple Notes & Semantic Search**](https://youtu.be/Ha-O8jwoh9E) — Connect your AI to Apple Notes with BERT-powered semantic search |\n| [![Apple Contacts](https://img.youtube.com/vi/POjUyFA7wDI/mqdefault.jpg)](https://youtu.be/POjUyFA7wDI) | [**Apple Contacts**](https://youtu.be/POjUyFA7wDI) — Search, create, and manage contacts from your AI assistant |\n| [![Apple Reminders](https://img.youtube.com/vi/AgcxHeTji1k/mqdefault.jpg)](https://youtu.be/AgcxHeTji1k) | [**Apple Reminders**](https://youtu.be/AgcxHeTji1k) — Full CRUD for reminders and lists via any MCP client |\n| [![Access Control](https://img.youtube.com/vi/ApIAIc4MQUI/mqdefault.jpg)](https://youtu.be/ApIAIc4MQUI) | [**Access Control**](https://youtu.be/ApIAIc4MQUI) — Configure exactly which data your AI can access |\n\n## What Can It Do?\n\n| Category | Tools | Description |\n|----------|-------|-------------|\n| **Notes** | `search_notes`, `list_notes`, `get_note`, `open_note`, `notes_tags`, `notes_search_by_tag`, `notes_index` | Search, browse, and read Apple Notes |\n| **Notes (Semantic)** | `notes_semantic_search`, `notes_smart_search`, `notes_rebuild_index`, `notes_index_stats` | BERT-powered semantic search across all your notes |\n| **Reminders** | `list_reminder_lists`, `search_reminders`, `list_reminders`, `get_reminder`, `create_reminder`, `create_reminders_batch`, `complete_reminder`, `delete_reminder`, `edit_reminder`, `edit_reminders_batch`, `open_reminders`, `create_reminder_list`, `delete_reminder_list` | Full CRUD for Apple Reminders |\n| **Contacts** | `list_contact_groups`, `search_contacts`, `list_contacts`, `get_contact`, `create_contact`, `edit_contact`, `delete_contact` | Search and manage Apple Contacts |\n| **Files** | `file_search`, `read_file`, `write_file` | Search and read/write files in granted folders |\n\n## Install\n\n### Homebrew (recommended)\n\n```bash\nbrew tap bjenkinsgit/tap\nbrew install psyxe-mcp\n```\n\nThis installs everything — binary, Swift helpers, FFmpeg, and the BERT model. No compilation required.\n\n### Build from Source\n\n```bash\ngit clone https://github.com/bjenkinsgit/psyxe-mcp.git\ncd psyxe-mcp\n./build.sh\n```\n\nThe build script handles everything automatically:\n- Installs Homebrew, Rust, FFmpeg, and pkg-config if missing\n- Builds the MCP server binary (Rust)\n- Builds Swift helpers for Reminders and Contacts\n- Copies helpers next to the binary\n- Pre-downloads the BERT model (~90MB) so first search is instant\n\nBuild without semantic search (skips FFmpeg and BERT):\n\n```bash\n./build.sh --no-memvid\n```\n\n**Requirements:** macOS 12+ (Monterey or later). Xcode Command Line Tools will be prompted if not installed.\n\nThe binary and helpers are in `target/release/`. Use the full path when configuring your MCP client.\n\n### Install Apple Shortcuts (optional)\n\nTwo shortcuts enable linking Reminders to file artifacts:\n\n```bash\n./install-shortcuts.sh\n```\n\nThis opens each shortcut in Shortcuts.app for you to approve.\n\n## Configure Your MCP Client\n\nIf you installed via Homebrew, the command is just `psyxe-mcp` (it's in your PATH). If you built from source, use the full path: `/Users/yourname/src/psyxe-mcp/target/release/psyxe-mcp`.\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add psyxe -- psyxe-mcp\n```\n\nOr edit `~/.claude/claude_mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"psyxe\": {\n      \"command\": \"psyxe-mcp\"\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"psyxe\": {\n      \"command\": \"psyxe-mcp\"\n    }\n  }\n}\n```\n\n### Cursor\n\nOpen Settings → MCP Servers → Add new server:\n\n```json\n{\n  \"psyxe\": {\n    \"command\": \"psyxe-mcp\"\n  }\n}\n```\n\n### Windsurf\n\nEdit `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"psyxe\": {\n      \"command\": \"psyxe-mcp\"\n    }\n  }\n}\n```\n\n### OpenAI Codex CLI\n\nEdit `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.psyxe]\ncommand = \"psyxe-mcp\"\n```\n\n> **Note:** If you built from source instead of using Homebrew, replace `psyxe-mcp` with the full path to the binary (e.g., `/Users/yourname/src/psyxe-mcp/target/release/psyxe-mcp`).\n\n## Access Control\n\nBy default, the MCP server has full access to all your Notes, Reminders, Contacts, and files. To restrict what your AI can see, use the built-in access control CLI to create and manage `~/.psyxe/access.toml`.\n\nNo manual file editing is needed — the CLI creates the file with secure permissions (owner-only read/write) on first use.\n\n### Quick Start\n\n```bash\n# 1. See what's available\npsyxe-mcp access discover reminders\npsyxe-mcp access discover notes\n\n# 2. Grant access to only what the AI should see\npsyxe-mcp access grant reminders \"Work\"\npsyxe-mcp access grant notes \"Projects\"\n\n# 3. Verify your restrictions\npsyxe-mcp access list\n```\n\nOnce any rule is set for a category, only explicitly granted resources are accessible — everything else in that category is denied.\n\n### Discover What's Available\n\n```bash\n# See your reminder lists\npsyxe-mcp access discover reminders\n\n# See your contact groups\npsyxe-mcp access discover contacts\n\n# See your note folders\npsyxe-mcp access discover notes\n\n# See common file locations\npsyxe-mcp access discover files\n```\n\n### Grant / Revoke Access\n\n```bash\n# Only allow access to specific reminder lists\npsyxe-mcp access grant reminders \"Work\"\npsyxe-mcp access grant reminders \"Shopping\" --rw    # read-write\n\n# Only allow access to a specific contact group\npsyxe-mcp access grant contacts \"iCloud\"\n\n# Only allow access to specific note folders\npsyxe-mcp access grant notes \"Projects\"\n\n# Grant file access to a folder\npsyxe-mcp access grant files \"/Users/you/Documents\" --rw\n\n# Revoke access\npsyxe-mcp access revoke reminders \"Shopping\"\n\n# See current restrictions\npsyxe-mcp access list\n\n# Remove all restrictions (restore full access)\npsyxe-mcp access reset\n```\n\nAccess rules are stored in `~/.psyxe/access.toml` with owner-only permissions (`chmod 600`). The server refuses to load the config if it is group- or world-readable, preventing other processes from tampering with access rights.\n\n## Semantic Search\n\nWhen built with the `memvid` feature (enabled by default), the server includes BERT-powered semantic search for Apple Notes. This uses [memvid-rs](https://github.com/bjenkinsgit/memvid-rs) to encode your notes into a searchable vector index.\n\n### First Use\n\nThe first time you (or your AI assistant) run a semantic search, the server will build an index of all your notes. This takes a few minutes depending on how many notes you have. Subsequent searches are instant.\n\n```bash\n# Or ask your AI assistant: \"search my notes for machine learning concepts\"\n# It will automatically build the index on first use.\n```\n\n### How It Works\n\n1. All notes are fetched from Notes.app\n2. Each note is chunked and encoded with a BERT model (384-dimensional embeddings)\n3. Chunks are stored as QR codes in a ProRes video file (compact, durable archive)\n4. A vector index (HNSW) enables instant semantic similarity search\n5. The index auto-detects when notes change and prompts for rebuild\n\n### Try It Out\n\nWe've included [sample notes](examples/sample-notes.md) designed to showcase semantic search:\n\n```bash\n# Load 10 sample notes into Apple Notes\n./examples/load-sample-notes.sh\n\n# Then ask your AI assistant to rebuild the index and try queries like:\n#   \"retirement savings\"  → finds Tax Strategy (never mentions \"retirement\")\n#   \"Italian cooking\"     → finds Carbonara recipe (never says \"Italian\")\n```\n\nSee [examples/sample-notes.md](examples/sample-notes.md) for the full list of demo queries.\n\n### Choosing a Different BERT Model\n\nThe default model (`sentence-transformers/all-MiniLM-L6-v2`, 384 dimensions) balances speed and quality. You can swap in any HuggingFace BERT-family sentence-transformer model.\n\n**Via environment variable:**\n```bash\nMEMVID_MODEL_NAME=BAAI/bge-small-en-v1.5 target/release/psyxe-mcp warmup\n```\n\n**Via config file** — create `memvid_config.toml` in the repo root or next to the binary:\n```toml\n[ml]\nmodel_name = \"BAAI/bge-small-en-v1.5\"\n```\n\nAfter changing models, rebuild the index (ask your AI assistant or run warmup again).\n\n**Popular alternatives:**\n\n| Model | Dimensions | Trade-off |\n|-------|-----------|-----------|\n| `sentence-transformers/all-MiniLM-L6-v2` | 384 | Default. Fast, good quality |\n| `BAAI/bge-small-en-v1.5` | 384 | Retrieval-optimized, slightly better for search |\n| `sentence-transformers/all-mpnet-base-v2` | 768 | Higher quality, ~2x slower |\n| `BAAI/bge-base-en-v1.5` | 768 | Best retrieval quality, needs query prefix |\n\nFor instruction-tuned models (like BGE), add query/document prefixes:\n```toml\n[ml]\nmodel_name = \"BAAI/bge-small-en-v1.5\"\nembedding_query_prefix = \"Represent this sentence for searching relevant passages: \"\nembedding_document_prefix = \"\"\n```\n\n### Remote Embedding API\n\nUse any OpenAI-compatible embedding endpoint instead of local BERT:\n\n```toml\n[ml]\nembedding_provider = \"remote\"\n```\n\nThen set the endpoint via environment variables:\n\n```bash\nexport EMBEDDING_API_URL=\"http://localhost:11434/v1/embeddings\"  # Ollama\nexport EMBEDDING_API_MODEL=\"nomic-embed-text\"\n```\n\nWorks with OpenAI, Ollama, vLLM, LM Studio, or any OpenAI-compatible endpoint.\n\n### Without Semantic Search\n\nBuild without memvid to skip the FFmpeg/BERT dependency entirely (no `brew install` needed):\n\n```bash\ncargo build --release --no-default-features\n```\n\nNotes tools still work — they fall back to AppleScript-based text search. All other tools (Reminders, Contacts, Files) are unaffected.\n\n## macOS Permissions\n\nOn first use, macOS will prompt you to grant permission for:\n\n- **Notes** — \"osascript\" wants to access Notes\n- **Reminders** — \"reminders-helper\" wants to access Reminders\n- **Contacts** — \"contacts-helper\" wants to access Contacts\n\nApprove these in the dialog that appears. You can review/revoke them later in System Settings → Privacy & Security.\n\n## Architecture\n\n```\n┌─────────────────┐     stdio (JSON-RPC)     ┌──────────────┐\n│  Claude Code /   │ ◄─────────────────────► │  psyxe-mcp   │\n│  Claude Desktop  │                          │  (MCP server) │\n└─────────────────┘                          └──────┬───────┘\n                                                     │\n                                    ┌────────────────┼────────────────┐\n                                    ▼                ▼                ▼\n                             ┌────────────┐  ┌─────────────┐  ┌───────────┐\n                             │ AppleScript │  │ Swift Helper│  │  memvid   │\n                             │ (Notes)     │  │ (EventKit,  │  │ (BERT +   │\n                             │             │  │  Contacts)  │  │  ProRes)  │\n                             └──────┬──────┘  └──────┬──────┘  └─────┬─────┘\n                                    ▼                ▼               ▼\n                             ┌────────────┐  ┌─────────────┐  ┌───────────┐\n                             │  Notes.app  │  │   EventKit  │  │ NoteStore │\n                             │             │  │   Contacts  │  │  SQLite   │\n                             └────────────┘  └─────────────┘  └───────────┘\n```\n\nThe MCP server is a thin stdio bridge. All the real work happens in `psyxe-mcp-core`, the open-source library that provides direct access to macOS-native APIs.\n\n## Configuration\n\n### Semantic Search (memvid)\n\nPlace a `memvid_config.toml` in the working directory or next to the binary:\n\n```toml\n[chunking]\nchunk_size = 700\noverlap = 100\n\n[ml]\ndevice = \"metal\"    # auto | cpu | cuda | metal\n\n[qr]\nerror_correction = \"low\"\nversion = 40\n\n[video]\ncodec = \"prores_ks\"\nprores_profile = \"proxy\"\nlibrary_log_level = \"error\"\n```\n\nSee [memvid-rs](https://github.com/bjenkinsgit/memvid-rs) for all configuration options.\n\n### Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `RUST_LOG` | Log level (default: `info`). Logs go to stderr. |\n| `TOOLS_JSON` | Path to custom tools.json (overrides embedded) |\n\n## Troubleshooting\n\n**\"osascript is not allowed to send keystrokes\"**\nGrant Accessibility permission: System Settings → Privacy & Security → Accessibility\n\n**\"reminders-helper\" wants to access your Reminders**\nClick Allow. If you previously denied, re-enable in System Settings → Privacy & Security → Reminders.\n\n**Semantic search is slow on first run**\nThe BERT model downloads on first use (~90MB). Subsequent runs use the cached model. Index building speed depends on note count — Metal GPU acceleration helps significantly on Apple Silicon.\n\n**Notes search returns stale results**\nThe server monitors for changes and will prompt your AI assistant to rebuild the index. You can also force it: ask your assistant to \"rebuild the notes index\".\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n\nThis project uses FFmpeg at runtime for ProRes video encoding only (LGPL codec). No GPL-licensed codecs (x264, x265, etc.) are used.\n\n## Credits\n\nBuilt on [psyxe-mcp-core](crates/mcp-core/), powered by [memvid-rs](https://github.com/bjenkinsgit/memvid-rs) for semantic search.\n",
  "bytes": 13656,
  "sha": "f67b1707ce17f7dce5a6bc7cfe4298f3e5c36495bb5ae3408cd4940bd2fd4906",
  "repo_slug": "bjenkinsgit/psyxe-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bjenkinsgit_psyxe_mcp_0c9d0e3f/readme"
}