kosshi-mcp

免責事項 / Disclaimer

これは非公式の個人プロジェクトです。Kosshi の開発元（しろくまMAKE）は、本ツールの動作保証・サポートを一切行いません。 本サーバーは Kosshi の AppleScript 機能を使います。この機能は Kosshi 側で「実験的（Experimental）」と位置づけられており、アップデートにより予告なく変更される可能性があります。その場合、本 MCP サーバーが動作しなくなる可能性があります。

This is an unofficial personal project. The developer of Kosshi (しろくまMAKE) provides no warranty or support for this tool. This server uses Kosshi's AppleScript automation, which Kosshi labels as experimental. It may change without notice in future updates, which may cause this MCP server to stop working.

Kosshi のアウトラインデータを読み取る MCP（Model Context Protocol）サーバーです。Claude Desktop から Kosshi のデータを参照できるようになります。読み取り専用です。

An MCP (Model Context Protocol) server that reads outline data from Kosshi. It allows Claude Desktop to access your Kosshi data. Read-only.

仕組み / How it works

本サーバーは Kosshi のデータベースファイルを直接読みません。Kosshi アプリに AppleScript で問い合わせます。そのため、node にフルディスクアクセスを与える必要はありません。必要な権限は「オートメーション（node → Kosshi）」だけです。

This server does not read Kosshi's database file directly. It queries the Kosshi app via AppleScript, so node does not need Full Disk Access. The only permission required is Automation (node → Kosshi).

提供ツール / Tools

ツール名 / Tool	説明 / Description
get_outline	アウトラインをタブ字下げのテキストで取得する。rootId で起点、depth で深さを指定できる / Retrieve the outline as tab-indented text. Optional rootId and depth
get_children	指定 ID の直下の子行を取得する。ID を省略すると最上位の行を返す / Retrieve direct child rows of a given ID (top-level rows if omitted)
search	タイトルとノートをキーワードで検索する（大文字小文字を区別しない）/ Case-insensitive keyword search in topics and notes
get_tasks	未完了タスク（[ ] を含む行）を取得する / Retrieve incomplete tasks (rows containing [ ])
get_bookmarked	ブックマーク済み行を一覧取得する / List all bookmarked rows

search と get_tasks は、件数を指定しない場合 200 件まで返します（最大 1000 件）。

search and get_tasks return up to 200 rows by default (maximum 1000).

必要環境 / Requirements

• macOS
• Kosshi 1.21.0 以降 / Kosshi 1.21.0 or later
• Node.js
• Claude Desktop

セットアップ / Setup

1. Kosshi の AppleScript 機能を有効にする / Enable AppleScript in Kosshi

Kosshi を開き、Option キーを押しながら「ヘルプ」メニューを開いて Developer Settings を表示する（または 設定 → Kosshi → Developer）。次の 2 つを有効にする。

Open Kosshi, hold the Option key and open the Help menu to show Developer Settings (or Settings → Kosshi → Developer). Turn on both:

• Developer Mode
• AppleScript Automation (Experimental)

2. リポジトリをクローンする / Clone the repository

git clone https://github.com/TsutomuZ/kosshi-mcp.git
cd kosshi-mcp/kosshi-mcp

3. 依存パッケージをインストールしてビルドする / Install dependencies and build

npm install
npm run build

4. Claude Desktop の設定に追加する / Add to Claude Desktop config

~/Library/Application Support/Claude/claude_desktop_config.json の mcpServers に以下を追加する。パスは実際のクローン先に合わせて変更すること。

Add the following to the mcpServers section of ~/Library/Application Support/Claude/claude_desktop_config.json. Adjust the path to match your actual clone location.

{
  "mcpServers": {
    "kosshi": {
      "command": "node",
      "args": ["/Users/<your-username>/Documents/GitHub/kosshi-MCP/kosshi-mcp/dist/index.js"]
    }
  }
}

5. Claude Desktop を再起動する / Restart Claude Desktop

初回の呼び出し時に「node が Kosshi を操作しようとしています」という確認が表示された場合は「OK」を選ぶ。

If macOS asks whether node may control Kosshi on first use, click "OK".

トラブルシューティング / Troubleshooting

メッセージ / Message	対処 / Fix
Kosshi の AppleScript 機能が無効になっている	セットアップ手順 1 の 2 項目を有効にする / Enable both settings in Setup step 1
node に Kosshi を操作する許可がない	システム設定 → プライバシーとセキュリティ → オートメーション で node の Kosshi を有効にする / Enable Kosshi under node in System Settings → Privacy & Security → Automation

技術メモ / Technical note

Kosshi 1.21.0 の AppleScript 辞書は、osascript で読み込むと「corrupted dictionary (-2705)」エラーになります。本サーバーはアプリ名を変数で渡し、コマンドを Apple Event コード（例: «event KshSFind»）で直接指定して、このエラーを回避しています。

Kosshi 1.21.0's AppleScript dictionary fails to load in osascript with "corrupted dictionary (-2705)". This server avoids the error by passing the app name as a variable and calling commands by their raw Apple Event codes (e.g. «event KshSFind»).

変更履歴 / Changelog

2.0.0

• データベースを直接読む方式から、AppleScript で Kosshi に問い合わせる方式に変更した。フルディスクアクセスが不要になった。

• get_recent を削除した。Kosshi の AppleScript が日付を返さないため。

• README のツール一覧を実装に合わせた。get_tasks（1.1.0 から実装済み）を記載し、実装されていない get_incomplete の記載を削除した。

• better-sqlite3 への依存を削除した。

• Switched from reading the database directly to querying Kosshi via AppleScript. Full Disk Access is no longer required.

• Removed get_recent, because Kosshi's AppleScript does not return dates.

• Updated the README tool list to match the implementation: documented get_tasks (implemented since 1.1.0) and removed get_incomplete, which was never implemented.

• Removed the better-sqlite3 dependency.

Credits

Built with the assistance of Claude (Anthropic).