Skip to main content
Glama
AI Coach MCP Server

AI Coach MCP Server

by aic0t

AI Coach MCP Server

MCP server that connects Claude to the AI Coach desktop pet running on the same machine. The mascot on the desktop reacts to the conversation: it shows its state, accepts care, speaks a short message, acts out what the assistant is doing, previews a local file, and stores the user's memos.

日本語の説明は下にあります。

Requirements

  • The AI Coach desktop app, installed and running (macOS 26+ / Windows 10+). Download it from https://aic0t.com. This server does nothing on its own — it is a client of the app's Local Automation API.

  • Node.js 22 or later (bundled with Claude for macOS and Windows).

Related MCP server: screenmcp-claude-plugin

Install

Install the .mcpb bundle from the Releases page by opening it with Claude Desktop.

Claude Code / Cursor

npx @aic0t/ai-coach-mcp --help
claude mcp add -s global ai-coach -- npx -y @aic0t/ai-coach-mcp

The AI Coach app also generates the same snippet for you under AI Settings → Integration.

Tools

Tool

What it does

Changes state

open_ai_coach_dashboard

Show mascot state and open the dashboard

no

refresh_ai_coach_status

Re-read state for the dashboard view

no

prepare_ai_coach_care

List care actions that are currently possible

no

commit_ai_coach_care

Apply a care action the user confirmed

yes

show_ai_coach_message

Show a short text in the speech bubble

yes

report_ai_coach_activity

Let the mascot act out the assistant's activity

yes

show_ai_coach_file

Preview a local file in the app's own viewer

yes

show_ai_coach_git_graph

Show a local repository's Git graph in the app

yes

list_ai_coach_notes

List memos, newest first (excerpts only)

no

read_ai_coach_note

Read one memo's Markdown body

no

search_ai_coach_notes

Search memos by title and body

no

write_ai_coach_note

Create, replace or append to a memo

yes

delete_ai_coach_note

Move a memo to the trash

yes (recoverable)

set_ai_coach_care_confirmation

Remember the dashboard's confirmation choice

yes

Care actions never run on the model's own initiative: prepare_ai_coach_care only reports what is possible, and commit_ai_coach_care is reachable only from an explicit click in the dashboard view.

How it connects

The AI Coach app writes a discovery file (runtime.json) into its application-support directory containing a per-session endpoint and token. This server reads that file on every connection attempt, then speaks the Local Automation API over a Unix domain socket (macOS) or a named pipe (Windows). Nothing leaves the machine, and no credentials are ever entered by the user.

First connection asks the user. The token in runtime.json is readable by any process running as the same user, so the app also asks the user to approve the connecting program itself. The first tool call therefore fails with app_busy / client_approval_pending while AI Coach shows a dialog naming the program, its location and its code signature. Approve it there and retry; the decision is remembered per executable, and can be reviewed or revoked under AI settings → Connect. Choosing "allow, except memos" keeps the connection but withholds the note.* tools.

Privacy Policy

Full policy: https://aic0t.com/privacy

This server runs locally and talks only to the AI Coach app on the same machine. It has no backend of its own and sends no telemetry.

  • What it reads. Mascot state (health, hunger, tiredness, mood, growth stage, name) and, when a memo tool is called, the memos the user asked for. Memo bodies are returned to the model only for read_ai_coach_note and search_ai_coach_notes.

  • What it never returns to the model. File contents, image data and full paths handled by show_ai_coach_file, and the commit history (messages, authors, hashes) and full path of a repository shown with show_ai_coach_git_graph. Those are rendered in the app's own windows on the user's screen; the tool result carries only a success or failure status and, for the Git graph, the folder name plus branch, commit and ref counts. The session token from runtime.json is never logged or returned.

  • Where data is stored. Memos and mascot state live in the AI Coach app's local data directory on the user's machine. This server stores nothing except a small preferences file recording the dashboard confirmation choice.

  • Third-party sharing. None. No data is transmitted off the device by this server.

  • Retention. This server retains nothing between runs beyond that preferences file. Data the app stores is retained and deleted by the app, under the user's control.

  • Contact. contact.aicoach@gmail.com

Development

npm ci && npm run build && npm test
npm run inspector

npm run build produces dist/server/main.js (a single self-contained ESM file), dist/view/mcp-app.html (the dashboard view, inlined into one HTML file) and dist/THIRD-PARTY-NOTICES.md. Those three files are the whole distributable — no node_modules ships with the bundle.

License

MIT — see LICENSE.

Because dist/ embeds its dependencies, the copyright notices and license texts of every bundled package are reproduced in dist/THIRD-PARTY-NOTICES.md, which is generated from the bundler's own module graph on each build and ships with both the .mcpb and the desktop app.


日本語

AI Coach — 卵から育てるデスクトップペット — を Claude から扱うための MCP サーバーです。デスクトップのキャラクターが会話に反応し、様子を見せ、世話を受け、短い言葉を話し、 作業の進捗を体で知らせ、ローカルファイルをプレビューし、メモを預かります。

必要なもの

  • AI Coach 本体アプリ(macOS 26 以降 / Windows 10 以降)がインストール済みで起動していること。 https://aic0t.com から入手できます。本サーバー単体では何もできません。

  • Node.js 22 以降(Claude の macOS 版 / Windows 版には同梱されています)。

導入

Claude Desktop では Releases の .mcpb を開くだけ です。Claude Code / Cursor 用の設定は、AI Coach 本体の「AI 設定 → 連携」からコピーできます。

つなぎ方

本体アプリがセッションごとの endpoint とトークンを runtime.json に書き出し、本サーバーが接続の たびにそれを読み直して、Unix ドメインソケット(macOS)または名前付きパイプ(Windows)で Local Automation API を話します。通信は端末内で完結し、ユーザーが認証情報を入力する場面はありません。

初回接続では本体アプリが確認します。 runtime.json のトークンは同じユーザー権限のプロセスなら 読めてしまうため、本体アプリは接続してきたプログラム自体の承認をユーザーに求めます。最初のツール 呼び出しは app_busy / client_approval_pending で失敗し、AI Coach 側にプログラム名・場所・署名を 示すダイアログが出ます。そこで許可してから再実行してください。判断は実行ファイル単位で記憶され、 「AI 設定 → 連携」で確認・取り消しができます。「メモ以外を許可」を選ぶと、接続は通りますが note.* のツールは使えません。

ライセンス

MIT(LICENSE)。dist/ は依存パッケージを取り込んだ複製物なので、同梱した各パッケージの 著作権表示とライセンス条文は dist/THIRD-PARTY-NOTICES.md に収めてあります(ビルドのたびに バンドラのモジュールグラフから生成し、.mcpb にも本体アプリにも同梱します)。

プライバシー

正式なポリシーは https://aic0t.com/privacy です。show_ai_coach_file で扱ったファイルの本文・ 画像データ・フルパス、および show_ai_coach_git_graph で表示したリポジトリのコミット履歴(メッセージ・ 作者・ハッシュ)とフルパスはモデルへ返さず、本体アプリの画面に表示するだけです(Git グラフの結果は フォルダ名とブランチ・コミット数・参照数の要約だけです)。メモ本文がモデルへ 渡るのは read_ai_coach_note と search_ai_coach_notes を呼んだときに限られます。端末外への送信と テレメトリはありません。

Available Tools

14 tools
commit_ai_coach_careCommit AI Coach careB
Idempotent

Apply a care action that the user confirmed in the dashboard.

Inputs: action (required), mascotId (required), previewToken (required), locale, +1 more. Returns: error, mascots, preview, appLocale, +7 more

delete_ai_coach_noteDelete an AI Coach memoA
DestructiveIdempotent

Move one memo in AI Coach to the trash (recoverable). Ask the user first unless they asked for the deletion themselves; AI Coach also asks them to confirm on screen — note_confirmation_denied means they declined.

Inputs: noteId (required), locale, idempotencyKey.

list_ai_coach_notesList AI Coach memosA
Read-only

List the user's memos in AI Coach, newest first: noteId, title, modified time, size, group and a short excerpt — not the full body (use read_ai_coach_note for that). Pass 'group' to list one group only, or an empty string for ungrouped memos. Read-only.

Inputs: group, limit, locale, offset.

open_ai_coach_dashboardOpen AI Coach dashboardB
Read-only

Show the current state of the AI Coach desktop mascots and open an interactive dashboard. Read-only.

Inputs: locale. Returns: error, mascots, preview, appLocale, +7 more

prepare_ai_coach_carePrepare AI Coach careA
Read-only

Show which care actions (feed, sleep, wake, walk, nurse) are currently possible for a mascot. Changes nothing; the user must confirm in the dashboard.

Inputs: locale, actions, mascotId. Returns: error, mascots, preview, appLocale, +7 more

read_ai_coach_noteRead an AI Coach memoA
Read-only

Read the Markdown body of one memo in AI Coach. When 'truncated' is true, call again with offsetBytes = offsetBytes + returnedBytes. Keep the returned modifiedAt and pass it as expectedModifiedAt when you later write to the same memo. Read-only.

Inputs: noteId (required), locale, maxBytes, offsetBytes.

refresh_ai_coach_statusRefresh AI Coach statusA
Read-only

Re-read the AI Coach mascot state for the dashboard view. Read-only.

Inputs: locale. Returns: error, mascots, preview, appLocale, +7 more

report_ai_coach_activityReport your activity to the mascotA
Idempotent

Let the AI Coach mascot act out what you are doing, with its own animation and speech bubble. Call with 'thinking' or 'working' when starting a task (optionally with a short label), 'waiting' when you need the user, 'succeeded' or 'failed' when you finish. Repeats of the same state are not re-announced, so calling on every step is safe.

Inputs: state (required), label, locale, mascotId, +1 more.

search_ai_coach_notesSearch AI Coach memosA
Read-only

Search the user's AI Coach memos by title and body text (case-insensitive substring). Returns matching memos with a snippet around the hit. Pass 'group' to search one group only, or an empty string for ungrouped memos. Read-only.

Inputs: query (required), group, limit, locale.

set_ai_coach_care_confirmationRemember the dashboard confirmation choiceA
Idempotent

Remember whether the AI Coach dashboard asks for confirmation before its own care buttons take effect. Dashboard use only; care that the model asks for is always confirmed by the user.

Inputs: skipCareConfirmation (required), locale. Returns: error, updatedAt, protocolVersion, viewPreferences

show_ai_coach_filePreview a local file in AI CoachA
Idempotent

Open a safe local preview beside the AI Coach mascot (md, markdown, txt, mmd, mermaid, html, htm, jpg, jpeg, png, heic, webp, svg; HTML is sandboxed). The file is read only by the AI Coach app; its contents are never returned to the model. Use only for a file the user asked to preview or one created in the current task.

Inputs: path (required), locale, mascotId.

show_ai_coach_git_graphShow a repository's Git graph in AI CoachA
Idempotent

Open the commit graph (branches, tags, merges, like VS Code's Git Graph) of a local Git repository folder beside the AI Coach mascot. Pass the absolute path of a folder that contains .git. The app reads .git locally and never runs git or touches the network; the model only receives a small summary (branch, commit and ref counts), never the history itself. Use only when the user asked to see the repository history or graph.

Inputs: path (required), locale, mascotId.

show_ai_coach_messageShow a message on the mascotA

Display a short text (up to 140 characters) in the AI Coach mascot's speech bubble. Text only; no images or links.

Inputs: text (required), locale, mascotId.

write_ai_coach_noteWrite an AI Coach memoA
Idempotent

Create, replace or append to a memo in AI Coach — a plain Markdown file on the user's machine, visible in the memo list right away. mode: 'create' (default) / 'replace' / 'append' (also for bodies over the per-call limit). Pass 'group' to file it under a folder, created if missing. When changing an existing memo, read it first and pass its modifiedAt as expectedModifiedAt so the user's own edits are not overwritten. AI Coach asks the user to confirm, so the call can take a few seconds; note_confirmation_denied means they declined.

Inputs: content (required), mode, group, title, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct action: dashboard display vs state refresh, care preview vs commit, arbitrary message vs activity report, and the note CRUD tools are clearly separated. Even where two tools touch the dashboard or speech bubble, the descriptions define non-overlapping responsibilities.

    Naming Consistency5/5

    All tools follow a consistent verb_ai_coach_[noun] pattern (open, prepare, refresh, commit, show, report, list, read, search, write, delete, set). The naming convention is uniform and the verb clearly indicates the operation.

    Tool Count5/5

    14 tools is within the well-scoped range for a desktop companion server. Each tool supports a distinct aspect of the mascot experience or memo workflow and none feel redundant.

    Completeness5/5

    The set covers the full care lifecycle (prepare, confirm, commit), read-only status and dashboard access, messaging and activity reporting, local previews, and complete note CRUD plus search. There are no obvious dead ends or missing core operations.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers