psyXe MCP Server

psyXe MCP Server

AI アシスタントから Apple Notes、Reminders、Contacts にアクセスできるようにする MCP サーバーです。オプションで BERT を活用したセマンティック検索も利用できます。

すべてのツールは macOS ネイティブの API（AppleScript、EventKit、Contacts フレームワーク）を使ってローカルで実行されます。データが Mac の外部に送信されることはありません。API キーも不要です。

MCP を初めてお使いですか？ これが何か、お使いの環境で動作するか、データがどのように保護されるかといったよくある質問への回答は、FAQをご覧ください。

ビデオチュートリアル

	Apple Notes & Semantic Search — BERT を活用したセマンティック検索で、AI を Apple Notes に接続します
	Apple Contacts — AI アシスタントから連絡先を検索、作成、管理します
	Apple Reminders — あらゆる MCP クライアントからリマインダーとリストの CRUD を実行します
	Access Control — AI がアクセスできるデータを細かく設定します

何ができますか？

カテゴリー	ツール	説明
メモ	search_notes, list_notes, get_note, open_note, notes_tags, notes_search_by_tag, notes_index	Apple Notes の検索、閲覧、読み取り
メモ（セマンティック）	notes_semantic_search, notes_smart_search, notes_rebuild_index, notes_index_stats	すべてのメモを対象にした、BERT を活用したセマンティック検索
リマインダー	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	Apple Reminders の CRUD 全般
連絡先	list_contact_groups, search_contacts, list_contacts, get_contact, create_contact, edit_contact, delete_contact	Apple Contacts の検索と管理
ファイル	file_search, read_file, write_file	許可されたフォルダー内のファイルの検索、読み取り、書き込み

インストール

Homebrew（推奨）

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-config がない場合はインストールします
• MCP サーバーのバイナリ（Rust）をビルドします
• Reminders と Contacts 用の Swift ヘルパーをビルドします
• ヘルパーをバイナリの隣にコピーします
• 初回検索をすぐに行えるよう、BERT モデル（約90MB）を事前にダウンロードします

セマンティック検索を使わずにビルドする場合（FFmpeg と BERT をスキップ）：

./build.sh --no-memvid

要件： macOS 12 以降（Monterey 以降）。Xcode Command Line Tools がインストールされていない場合は、インストールを求められます。

バイナリとヘルパーは target/release/ にあります。MCP クライアントを設定する際は、フルパスを使用してください。

Apple Shortcuts をインストール（任意）

2 つのショートカットを使うと、リマインダーをファイルの成果物にリンクできます。

./install-shortcuts.sh

各ショートカットが Shortcuts.app で開くので、承認してください。

MCP クライアントを設定する

Homebrew でインストールした場合、コマンドは psyxe-mcp だけです（PATH に含まれています）。ソースからビルドした場合は、フルパス /Users/yourname/src/psyxe-mcp/target/release/psyxe-mcp を使用してください。

Claude Code（CLI）

claude mcp add psyxe -- psyxe-mcp

または、~/.claude/claude_mcp_config.json を編集します。

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

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json を編集します。

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

Cursor

「設定」→「MCP Servers」→「Add new server」を開きます。

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

Windsurf

~/.codeium/windsurf/mcp_config.json を編集します。

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

OpenAI Codex CLI

~/.codex/config.toml を編集します。

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

Note: 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

アクセスルールは、所有者のみがアクセスできる権限（chmod 600）で ~/.psyxe/access.toml に保存されます。他のプロセスがアクセス権を改ざんするのを防ぐため、グループまたは他のユーザーが読み取り可能な場合、サーバーは設定の読み込みを拒否します。

セマンティック検索

memvid 機能（デフォルトで有効）を使ってビルドすると、サーバーには Apple Notes 用の BERT ベースのセマンティック検索が含まれます。これは memvid-rs を使用してメモを検索可能なベクトルインデックスに変換します。

初回の使用

あなた（または AI アシスタント）が初めてセマンティック検索を実行すると、サーバーはすべてのメモのインデックスを作成します。メモの数によっては数分かかります。2 回目以降の検索は即座に完了します。

# 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 動画ファイル内の QR コードとして保存します（コンパクトで耐久性の高いアーカイブ）
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")

デモクエリの全リストについては、examples/sample-notes.mdを参照してください。

別の BERT モデルを選ぶ

デフォルトのモデル（sentence-transformers/all-MiniLM-L6-v2、384 次元）は、速度と品質のバランスに優れています。HuggingFace の BERT 系センテンス・トランスフォーマーモデルなら、どれでも使用できます。

環境変数を使用する場合：

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

設定ファイルを使用する場合 — リポジトリのルート、またはバイナリの隣に memvid_config.toml を作成します。

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

モデルを変更した後は、インデックスを再構築してください（AI アシスタントに依頼するか、ウォームアップを再実行します）。

人気の代替モデル：

モデル	次元数	トレードオフ
sentence-transformers/all-MiniLM-L6-v2	384	デフォルト。高速で品質も良好
BAAI/bge-small-en-v1.5	384	検索に最適化されており、検索精度がやや高い
sentence-transformers/all-mpnet-base-v2	768	品質は高いものの、速度は約 2 倍遅い
BAAI/bge-base-en-v1.5	768	検索品質が最も高いものの、クエリプレフィックスが必要

BGE のようなインストラクションチューニング済みモデルでは、クエリ／ドキュメントのプレフィックスを追加します。

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

リモート埋め込み API

ローカルの BERT の代わりに、OpenAI 互換の埋め込みエンドポイントを使用できます。

[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

メモのツールは引き続き動作し、AppleScript ベースのテキスト検索にフォールバックします。他のすべてのツール（リマインダー、連絡先、ファイル）には影響しません。

macOS の権限

初回の使用時に、macOS から次の権限の付与を求められます。

• Notes — 「osascript」が Notes へのアクセスを求めています
• Reminders — 「reminders-helper」が Reminders へのアクセスを求めています
• Contacts — 「contacts-helper」が Contacts へのアクセスを求めています

表示されるダイアログで許可してください。後から「システム設定」→「プライバシーとセキュリティ」で確認または取り消すことができます。

アーキテクチャ

┌─────────────────┐     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 ブリッジです。実際の処理はすべて、macOS ネイティブ API に直接アクセスできるオープンソースライブラリ psyxe-mcp-core が担います。

設定

セマンティック検索（memvid）

作業ディレクトリ、またはバイナリの隣に 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 を参照してください。

環境変数

変数	用途
RUST_LOG	ログレベル（デフォルト：info）。ログは stderr に出力されます。
TOOLS_JSON	カスタム tools.json のパス（埋め込みのものを上書きします）

トラブルシューティング

「osascript はキーストロークの送信を許可されていません」 アクセシビリティの権限を付与してください：システム設定 → プライバシーとセキュリティ → アクセシビリティ

「reminders-helper」がリマインダーへのアクセスを要求しています 「許可」をクリックしてください。以前に拒否した場合は、システム設定 → プライバシーとセキュリティ → リマインダーで再度有効にしてください。

初回実行時にセマンティック検索が遅い BERT モデルは初回使用時にダウンロードされます（約90MB）。2回目以降はキャッシュされたモデルを使用します。インデックスの構築速度はノートの数によって異なります。Apple Silicon では Metal GPU アクセラレーションによって大幅に高速化されます。

ノートの検索結果が古い サーバーは変更を監視し、AI アシスタントにインデックスの再構築を促します。次のように依頼して、手動で再構築することもできます：「ノートのインデックスを再構築して」。

ライセンス

Apache 2.0 — LICENSE を参照してください。

このプロジェクトは、ProRes 動画のエンコード時のみ、実行時に FFmpeg（LGPL コーデック）を使用します。GPL ライセンスのコーデック（x264、x265 など）は使用しません。

クレジット

psyxe-mcp-core を基盤とし、セマンティック検索には memvid-rs を利用しています。