Psyxe MCP

psyXe MCP服务器

一 MCP服务器 它使人工智能助手能够访问您的Apple Notes、提醒和联系人，并提供可选的BERT支持的语义搜索。

所有工具都通过macOS原生API（AppleScript、EventKit、Contacts框架）在本地运行。没有数据离开你的Mac。不需要API密钥。

MCP新手？ 看看这个 常见问题解答 有关这是什么、它是否适用于您的设置以及您的数据如何保持私密的常见问题的答案。

视频教程

它能做什么？

安装

自制（推荐）

brew tap bjenkinsgit/tap
brew install psyxe-mcp

这将安装所有内容——二进制、Swift助手、FFmpeg和BERT模型。无需编译。

从源代码构建

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

构建脚本会自动处理所有内容：

• 如果缺少Homebrew、Rust、FFmpeg和pkg配置，则安装它们
• 构建MCP服务器二进制文件（Rust）
• 为提醒和联系人构建Swift助手
• 复制二进制文件旁边的辅助程序
• 预下载BERT模型（约90MB），因此第一次搜索是即时的

无语义搜索构建（跳过FFmpeg和BERT）：

./build.sh --no-memvid

要求： macOS 12+（蒙特利或更高版本）。如果未安装Xcode命令行工具，则会提示。

二进制文件和辅助程序位于 target/release/。配置MCP客户端时使用完整路径。

安装Apple快捷方式（可选）

有两个快捷方式可以将提醒链接到文件工件：

./install-shortcuts.sh

这将打开Shortcuts.app中的每个快捷方式供您审批。

配置您的MCP客户端

如果你是通过Homebrew安装的，命令只是 psyxe-mcp （它在你的路径中）。如果从源代码构建，请使用完整路径： /Users/yourname/src/psyxe-mcp/target/release/psyxe-mcp.

克劳德代码（CLI）

claude mcp add psyxe -- psyxe-mcp

或编辑 ~/.claude/claude_mcp_config.json:

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

克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

光标

打开设置→ MCP服务器→ 添加新服务器：

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

帆板运动

编辑 ~/.codeium/windsurf/mcp_config.json:

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

OpenAI Codex命令行界面

编辑 ~/.codex/config.toml:

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

注： 如果您从源代码构建而不是使用Homebrew，请替换 psyxe-mcp 使用二进制文件的完整路径（例如。， /Users/yourname/src/psyxe-mcp/target/release/psyxe-mcp).

访问控制

默认情况下，MCP服务器可以完全访问您的所有笔记、提醒、联系人和文件。要限制您的AI可以看到的内容，请使用内置的访问控制CLI创建和管理 ~/.psyxe/access.toml.

无需手动编辑文件——CLI在首次使用时创建具有安全权限（仅限所有者读/写）的文件。

快速开始

# 1. See what's available
psyxe-mcp access discover reminders
psyxe-mcp access discover notes

# 2. Grant access to only what the AI should see
psyxe-mcp access grant reminders "Work"
psyxe-mcp access grant notes "Projects"

# 3. Verify your restrictions
psyxe-mcp access list

一旦为某个类别设置了任何规则，只有明确授予的资源才可访问，该类别中的其他所有资源都将被拒绝。

发现可用内容

# See your reminder lists
psyxe-mcp access discover reminders

# See your contact groups
psyxe-mcp access discover contacts

# See your note folders
psyxe-mcp access discover notes

# See common file locations
psyxe-mcp access discover files

授予/撤销访问权限

# Only allow access to specific reminder lists
psyxe-mcp access grant reminders "Work"
psyxe-mcp access grant reminders "Shopping" --rw    # read-write

# Only allow access to a specific contact group
psyxe-mcp access grant contacts "iCloud"

# Only allow access to specific note folders
psyxe-mcp access grant notes "Projects"

# Grant file access to a folder
psyxe-mcp access grant files "/Users/you/Documents" --rw

# Revoke access
psyxe-mcp access revoke reminders "Shopping"

# See current restrictions
psyxe-mcp access list

# Remove all restrictions (restore full access)
psyxe-mcp access reset

访问规则存储在 ~/.psyxe/access.toml 仅具有所有者权限(chmod 600).如果配置是组可读或世界可读的，服务器将拒绝加载配置，以防止其他进程篡改访问权限。

语义搜索

当与 memvid 该功能（默认启用），服务器包括基于BERT的Apple Notes语义搜索。这使用 memvid-rs 将笔记编码为可搜索的矢量索引。

首先使用

当你（或你的人工智能助手）第一次运行语义搜索时，服务器会为你的所有笔记建立一个索引。这需要几分钟的时间，具体取决于你有多少笔记。后续搜索是即时的。

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

运作原理

1. 所有笔记均从notes.app获取
2. 每个音符都用BERT模型（384维嵌入）进行分块和编码
3. 块以二维码的形式存储在ProRes视频文件中（紧凑、耐用的存档）
4. 矢量索引（HNSW）支持即时语义相似性搜索
5. 索引会自动检测笔记何时更改并提示重建

试试看

我们包括 示例注释 旨在展示语义搜索：

# 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")

看 示例/示例注释.md 查看演示查询的完整列表。

选择不同的BERT模型

默认模型(sentence-transformers/all-MiniLM-L6-v2384个维度）平衡了速度和质量。您可以在任何HuggingFace BERT家族句子转换器模型中进行交换。

通过环境变量：

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

通过配置文件 --创建 memvid_config.toml 在repo根目录中或二进制文件旁边：

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

更改模型后，重建索引（询问您的AI助手或再次运行预热）。

流行的替代方案：

对于指令调优模型（如BGE），添加查询/文档前缀：

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

远程嵌入API

使用任何与OpenAI兼容的嵌入端点，而不是本地BERT：

[ml]
embedding_provider = "remote"

然后通过环境变量设置端点：

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

适用于OpenAI、Ollama、vLLM、LM Studio或任何与OpenAI兼容的端点。

无语义搜索

构建时不使用memvid，完全跳过FFmpeg/BERT依赖关系（否 brew install 需要）：

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

Notes工具仍然有效——它们可以追溯到基于AppleScript的文本搜索。所有其他工具（提醒、联系人、文件）不受影响。

macOS权限

首次使用时，macOS会提示您授予以下权限：

• 备注 --“osascript”想要访问Notes
• 提醒事项 --“提醒助手”想要访问提醒
• 联系人 --“联系人助手”想要访问联系人

在出现的对话框中批准这些。您可以稍后在系统设置中查看/撤销它们→ 隐私和安全。

建筑

┌─────────────────┐     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   │
                             └────────────┘  └─────────────┘  └───────────┘

MCP服务器是一个精简的stdio网桥。所有真正的工作都发生在 psyxe-mcp-core，提供直接访问macOS原生API的开源库。

配置

语义搜索（memvid）

地点a memvid_config.toml 在工作目录中或二进制文件旁边：

[chunking]
chunk_size = 700
overlap = 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"

看 memvid-rs 对于所有配置选项。

环境变量

故障排除

“osascript不允许发送击键” 授予辅助功能权限：系统设置→ 隐私和安全→ 无障碍

“提醒助手”想要访问您的提醒 单击“允许”。如果之前拒绝，请在系统设置中重新启用→ 隐私和安全→ 提醒。

语义搜索在第一次运行时很慢 BERT模型在首次使用时下载（约90MB）。后续运行使用缓存的模型。索引构建速度取决于音符数量——Metal GPU加速对Apple Silicon有很大帮助。

Notes搜索返回过时的结果 服务器会监视更改，并提示您的AI助手重建索引。你也可以强制执行：让你的助手“重建笔记索引”。

许可证

Apache 2.0——请参阅 许可证.

此项目在运行时仅将FFmpeg用于ProRes视频编码（LGPL编解码器）。不使用GPL许可的编解码器（x264、x265等）。

学分