Ulysses MCP

🚀 Ulysses MCP Server

このUlysses MCP Serverは、AIアシスタントがmacOS上のUlyssesという執筆アプリケーションとやり取りできるようにするMCP（Model Context Protocol）サーバーです。

🚀 クイックスタート

このMCPサーバーは、Ulyssesのx-callback-url APIを介してUlyssesを自動化する包括的なツールを提供します。これにより、ClaudeやClineなどのAIアシスタントや他のMCP互換クライアントは、以下の操作が可能になります。

• 📝 シートの作成と管理 - 内容を含んだ新しいドキュメントを作成します。
• 📁 グループによる整理 - フォルダ構造を作成し、管理します。
• ✏️ 内容の追加 - 既存のシートにテキストを挿入または追加します。
• 🏷️ メタデータの添付 - シートにノート、キーワード、画像を追加します。
• 📖 内容の読み取り - シートの内容とメタデータを抽出します（認証が必要です）。
• 🧭 ナビゲーション - 特定のシート、グループ、または特別なセクションを開きます。
• 🔧 変更 - 項目を移動、コピー、名前変更、削除します（認証が必要です）。

✨ 主な機能

• 包括的なツールを提供し、Ulyssesを自動化できます。
• 複数のAIアシスタントやMCP互換クライアントとの互換性があります。
• 様々な操作（シートの作成、内容の追加、メタデータの添付など）が可能です。

📦 インストール

npmを使用する場合

npm install ulysses-mcp

ソースからインストールする場合

git clone https://github.com/sonofagl1tch/ulysses-mcp.git
cd ulysses-mcp
npm install
npm run build

ヘルパーアプリのビルド

⚠️ 重要: セキュリティ上の理由から、このリポジトリにはヘルパーアプリのバイナリが含まれていません。インストール後にローカルでビルドする必要があります。

インストール後、コールバック操作に必要なヘルパーアプリをビルドする必要があります。

npm run build-helper

これにより、Ulyssesからのコールバックを処理する小さなmacOSアプリケーションが作成されます。ヘルパーアプリは以下のように動作します。

• 必要なときに自動的に実行されます（手動で起動する必要はありません）。
• カスタムURLスキーム (ulysses-mcp-callback://) を登録します。
• コールバックが必要な操作（認証、内容の読み取りなど）を有効にします。
• バージョン管理には決してコミットしないでください（すでに.gitignoreに含まれています）。

詳細については、ヘルパーアプリのドキュメントを参照してください。

💻 使用例

基本的な使用法

新しいシートの作成

// 日記エントリーを作成する
{
  "tool": "ulysses_new_sheet",
  "arguments": {
    "text": "# Journal Entry - October 23, 2025\n\nToday I...",
    "group": "/Journal",
    "format": "markdown"
  }
}

キーワードの追加

// シートにタグを付けて整理する
{
  "tool": "ulysses_attach_keywords",
  "arguments": {
    "id": "sheet-identifier-here",
    "keywords": "Draft,Blog,Technical"
  }
}

内容の読み取り（認証が必要）

// まず、認証を行う
{
  "tool": "ulysses_authorize",
  "arguments": {
    "appname": "My AI Assistant"
  }
}
// Ulyssesで承認した後、トークンを使用して読み取る
{
  "tool": "ulysses_read_sheet",
  "arguments": {
    "id": "sheet-identifier-here",
    "text": "YES",
    "access_token": "your-access-token"
  }
}

高度な使用法

高度な使用法については、各操作の詳細な説明とコード例を参照してください。

📚 ドキュメント

アーキテクチャ、セキュリティ、プライバシー、認証に関する詳細な情報については、docs/ディレクトリ内の包括的なドキュメントを参照してください。

• アーキテクチャ - システムアーキテクチャ、データフロー、技術的な詳細
• 認証 - 認証モデル、アクセストークン、セキュリティ
• プライバシーとセキュリティ - プライバシー保証、セキュリティ機能、検証
• ドキュメントインデックス - 完全なドキュメントの概要

🔧 技術詳細

このサーバーはUlysses x-callback-url APIバージョン3を実装しています。詳細なAPIドキュメントについては、以下を参照してください。

• Ulysses x-callback-urlドキュメント
• Model Context Protocol

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。