psyXe MCP Server

io.github.bjenkinsgitPublished by GitHub account bjenkinsgitv0.1.10Updated Oct 24, 2026

Apple Notes, Reminders, and Contacts for AI assistants. BERT semantic search. macOS.

VerifiedSTDIODesktop onlyProductivity & WorkflowFiles & StorageKnowledge & Memory

Overview

AI-generated overview

Gives an AI assistant access to Apple Notes, Reminders and Contacts through macOS-native APIs, with optional BERT semantic search.

What you can do
Search, browse and read Apple Notes, filter by tag, and build a notes index. Run BERT semantic and smart search across all notes, rebuild the index and view index statistics. Manage Reminders and lists end to end, including search, create, edit, complete and delete. Search and manage Contacts and contact groups, including create, edit and delete. Search files in granted folders and read or write them.
When to use it
Use it when you want an assistant to read or manage Apple Notes, Reminders and Contacts on a Mac, or to search and read/write files in folders you grant. Semantic search is worth enabling when you need concept-level lookup across notes.
Requirements
macOS 12 or later only, run as a local stdio process; install via Homebrew or build from source (Xcode Command Line Tools, Rust, plus FFmpeg and a ~90MB BERT model for semantic search). macOS permission prompts for Notes, Reminders and Contacts must be approved on first use. No API keys required.
Before you install
By default it has full access to all notes, reminders, contacts and files; restrict scope with the built-in access control commands. Tools can create, edit and delete reminders, lists, contacts and files, so mistakes can lose data. If you switch to a remote embedding endpoint, note content is sent to that endpoint; the default local BERT mode keeps data on the Mac.

Installation

In SourceWeft

  1. Open psyXe MCP Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

psyXe MCP Server

An MCP server that gives AI assistants access to your Apple Notes, Reminders, and Contacts — with optional BERT-powered semantic search.

All tools run locally via macOS-native APIs (AppleScript, EventKit, Contacts framework). No data leaves your Mac. No API keys required.

New to MCP? Check out the FAQ for answers to common questions about what this is, whether it works with your setup, and how your data stays private.

Video Tutorials

[Notes & Semantic Search]Apple Notes & Semantic Search — Connect your AI to Apple Notes with BERT-powered semantic search
[Apple Contacts]Apple Contacts — Search, create, and manage contacts from your AI assistant
[Apple Reminders]Apple Reminders — Full CRUD for reminders and lists via any MCP client
[Access Control]Access Control — Configure exactly which data your AI can access

What Can It Do?

CategoryToolsDescription
Notessearch_notes, list_notes, get_note, open_note, notes_tags, notes_search_by_tag, notes_indexSearch, browse, and read Apple Notes
Notes (Semantic)notes_semantic_search, notes_smart_search, notes_rebuild_index, notes_index_statsBERT-powered semantic search across all your notes
Reminderslist_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_listFull CRUD for Apple Reminders
Contactslist_contact_groups, search_contacts, list_contacts, get_contact, create_contact, edit_contact, delete_contactSearch and manage Apple Contacts
Filesfile_search, read_file, write_fileSearch and read/write files in granted folders

Install

Homebrew (recommended)

bash
brew tap bjenkinsgit/tapbrew install psyxe-mcp

This installs everything — binary, Swift helpers, FFmpeg, and the BERT model. No compilation required.

Build from Source

bash
git clone https://github.com/bjenkinsgit/psyxe-mcp.gitcd psyxe-mcp./build.sh

The build script handles everything automatically:

  • Installs Homebrew, Rust, FFmpeg, and pkg-config if missing
  • Builds the MCP server binary (Rust)
  • Builds Swift helpers for Reminders and Contacts
  • Copies helpers next to the binary
  • Pre-downloads the BERT model (~90MB) so first search is instant

Build without semantic search (skips FFmpeg and BERT):

bash
./build.sh --no-memvid

Requirements: macOS 12+ (Monterey or later). Xcode Command Line Tools will be prompted if not installed.

The binary and helpers are in target/release/. Use the full path when configuring your MCP client.

Install Apple Shortcuts (optional)

Two shortcuts enable linking Reminders to file artifacts:

bash
./install-shortcuts.sh

This opens each shortcut in Shortcuts.app for you to approve.

Configure Your MCP Client

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

Claude Code (CLI)

bash
claude mcp add psyxe -- psyxe-mcp

Or edit ~/.claude/claude_mcp_config.json:

json
{  "mcpServers": {    "psyxe": {      "command": "psyxe-mcp"    }  }}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

json
{  "mcpServers": {    "psyxe": {      "command": "psyxe-mcp"    }  }}

Cursor

Open Settings → MCP Servers → Add new server:

json
{  "psyxe": {    "command": "psyxe-mcp"  }}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

json
{  "mcpServers": {    "psyxe": {      "command": "psyxe-mcp"    }  }}

OpenAI Codex CLI

Edit ~/.codex/config.toml:

toml
[mcp_servers.psyxe]command = "psyxe-mcp"

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

Access Control

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

No manual file editing is needed — the CLI creates the file with secure permissions (owner-only read/write) on first use.

Quick Start

bash
# 1. See what's availablepsyxe-mcp access discover reminderspsyxe-mcp access discover notes
# 2. Grant access to only what the AI should seepsyxe-mcp access grant reminders "Work"psyxe-mcp access grant notes "Projects"
# 3. Verify your restrictionspsyxe-mcp access list

Once any rule is set for a category, only explicitly granted resources are accessible — everything else in that category is denied.

Discover What's Available

bash
# See your reminder listspsyxe-mcp access discover reminders
# See your contact groupspsyxe-mcp access discover contacts
# See your note folderspsyxe-mcp access discover notes
# See common file locationspsyxe-mcp access discover files

Grant / Revoke Access

bash
# Only allow access to specific reminder listspsyxe-mcp access grant reminders "Work"psyxe-mcp access grant reminders "Shopping" --rw    # read-write
# Only allow access to a specific contact grouppsyxe-mcp access grant contacts "iCloud"
# Only allow access to specific note folderspsyxe-mcp access grant notes "Projects"
# Grant file access to a folderpsyxe-mcp access grant files "/Users/you/Documents" --rw
# Revoke accesspsyxe-mcp access revoke reminders "Shopping"
# See current restrictionspsyxe-mcp access list
# Remove all restrictions (restore full access)psyxe-mcp access reset

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

Semantic Search

When built with the memvid feature (enabled by default), the server includes BERT-powered semantic search for Apple Notes. This uses memvid-rs to encode your notes into a searchable vector index.

First Use

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

bash
# Or ask your AI assistant: "search my notes for machine learning concepts"# It will automatically build the index on first use.

How It Works

  1. All notes are fetched from Notes.app
  2. Each note is chunked and encoded with a BERT model (384-dimensional embeddings)
  3. Chunks are stored as QR codes in a ProRes video file (compact, durable archive)
  4. A vector index (HNSW) enables instant semantic similarity search
  5. The index auto-detects when notes change and prompts for rebuild

Try It Out

We've included sample notes designed to showcase semantic search:

bash
# Load 10 sample notes into Apple Notes./examples/load-sample-notes.sh
# Then ask your AI assistant to rebuild the index and try queries like:#   "retirement savings"  → finds Tax Strategy (never mentions "retirement")#   "Italian cooking"     → finds Carbonara recipe (never says "Italian")

See examples/sample-notes.md for the full list of demo queries.

Choosing a Different BERT Model

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

Via environment variable:

bash
MEMVID_MODEL_NAME=BAAI/bge-small-en-v1.5 target/release/psyxe-mcp warmup

Via config file — create memvid_config.toml in the repo root or next to the binary:

toml
[ml]model_name = "BAAI/bge-small-en-v1.5"

After changing models, rebuild the index (ask your AI assistant or run warmup again).

Popular alternatives:

ModelDimensionsTrade-off
sentence-transformers/all-MiniLM-L6-v2384Default. Fast, good quality
BAAI/bge-small-en-v1.5384Retrieval-optimized, slightly better for search
sentence-transformers/all-mpnet-base-v2768Higher quality, ~2x slower
BAAI/bge-base-en-v1.5768Best retrieval quality, needs query prefix

For instruction-tuned models (like BGE), add query/document prefixes:

toml
[ml]model_name = "BAAI/bge-small-en-v1.5"embedding_query_prefix = "Represent this sentence for searching relevant passages: "embedding_document_prefix = ""

Remote Embedding API

Use any OpenAI-compatible embedding endpoint instead of local BERT:

toml
[ml]embedding_provider = "remote"

Then set the endpoint via environment variables:

bash
export EMBEDDING_API_URL="http://localhost:11434/v1/embeddings"  # Ollamaexport EMBEDDING_API_MODEL="nomic-embed-text"

Works with OpenAI, Ollama, vLLM, LM Studio, or any OpenAI-compatible endpoint.

Without Semantic Search

Build without memvid to skip the FFmpeg/BERT dependency entirely (no brew install needed):

bash
cargo build --release --no-default-features

Notes tools still work — they fall back to AppleScript-based text search. All other tools (Reminders, Contacts, Files) are unaffected.

macOS Permissions

On first use, macOS will prompt you to grant permission for:

  • Notes — "osascript" wants to access Notes
  • Reminders — "reminders-helper" wants to access Reminders
  • Contacts — "contacts-helper" wants to access Contacts

Approve these in the dialog that appears. You can review/revoke them later in System Settings → Privacy & Security.

Architecture

┌─────────────────┐     stdio (JSON-RPC)     ┌──────────────┐│  Claude Code /   │ ◄─────────────────────► │  psyxe-mcp   ││  Claude Desktop  │                          │  (MCP server) │└─────────────────┘                          └──────┬───────┘                                                     │                                    ┌────────────────┼────────────────┐                                    ▼                ▼                ▼                             ┌────────────┐  ┌─────────────┐  ┌───────────┐                             │ AppleScript │  │ Swift Helper│  │  memvid   │                             │ (Notes)     │  │ (EventKit,  │  │ (BERT +   │                             │             │  │  Contacts)  │  │  ProRes)  │                             └──────┬──────┘  └──────┬──────┘  └─────┬─────┘                                    ▼                ▼               ▼                             ┌────────────┐  ┌─────────────┐  ┌───────────┐                             │  Notes.app  │  │   EventKit  │  │ NoteStore │                             │             │  │   Contacts  │  │  SQLite   │                             └────────────┘  └─────────────┘  └───────────┘

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

Configuration

Semantic Search (memvid)

Place a memvid_config.toml in the working directory or next to the binary:

toml
[chunking]chunk_size = 700overlap = 100
[ml]device = "metal"    # auto | cpu | cuda | metal
[qr]error_correction = "low"version = 40
[video]codec = "prores_ks"prores_profile = "proxy"library_log_level = "error"

See memvid-rs for all configuration options.

Environment Variables

VariablePurpose
RUST_LOGLog level (default: info). Logs go to stderr.
TOOLS_JSONPath to custom tools.json (overrides embedded)

Troubleshooting

"osascript is not allowed to send keystrokes" Grant Accessibility permission: System Settings → Privacy & Security → Accessibility

"reminders-helper" wants to access your Reminders Click Allow. If you previously denied, re-enable in System Settings → Privacy & Security → Reminders.

Semantic search is slow on first run The 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.

Notes search returns stale results The 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".

License

Apache 2.0 — see LICENSE.

This project uses FFmpeg at runtime for ProRes video encoding only (LGPL codec). No GPL-licensed codecs (x264, x265, etc.) are used.

Credits

Built on psyxe-mcp-core, powered by memvid-rs for semantic search.

Source: README.md at commit eab541d

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.10LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.