# ainote MCP server

Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.

## Links
- Registry page: https://www.getdrio.com/mcp/io-github-seunghan91-ainote
- Repository: https://github.com/seunghan91/ainote
- Website: https://docs.ainote.dev

## Install
- Command: `npx -y @ainote/mcp`
- Endpoint: https://api.ainote.dev/api/mcp
- Auth: Auth required by registry metadata

## Setup notes
- Remote header: Authorization (required; secret)
- Package: Npm @ainote/mcp v1.3.2
- Environment variable: AINOTE_API_KEY (required; secret)
- The upstream registry signals required auth or secrets.
- Remote endpoint: https://api.ainote.dev/api/mcp
- Header: Authorization

## Tools
- list_tasks - List all tasks from AI Note with advanced filtering, date ranges, location search, and sorting Endpoint: https://api.ainote.dev/api/mcp
- create_task - Create a new task in AI Note. Supports full task creation with dates, times, location, notes, and notifications. Endpoint: https://api.ainote.dev/api/mcp
- update_task - Update an existing task. All fields are optional except id. Endpoint: https://api.ainote.dev/api/mcp
- delete_task - Soft-delete a task by ID. Destructive but reversible within 30 days (TaskCleanupJob purges trash daily at 2am KST). Returns 404 if the task does not exist or is not owned by the authenticated user. Endpoint: https://api.ainote.dev/api/mcp
- list_categories - List all task categories for the authenticated user. Returns id/name/color/icon/task_count tuples. Read-only — use create_task with category_id to assign tasks to a category. Endpoint: https://api.ainote.dev/api/mcp
- list_papers - List notes/papers from AI Note. Supports keyword search across title and content, category filtering, pagination, and sorting. Returns id/title/content_preview/category_id/created_at. Use this when the user asks 'find my note about X', 'what did I write on Y', or wants to search their knowledge base. Endpoint: https://api.ainote.dev/api/mcp
- list_dev_docs - List dev documents under the dev/ category hierarchy. Filter by subcategory (claude, cursor, windsurf, copilot, docs, etc.), search by title, or filter by content type. Endpoint: https://api.ainote.dev/api/mcp
- get_dev_doc - Get a single dev document by title or id. Returns full content. Endpoint: https://api.ainote.dev/api/mcp
- create_dev_doc - Save a document to AI Note cloud for multi-device sync and persistent storage.

PRIMARY USE CASES:
- Memory files: ~/.claude/projects/.../memory/MEMORY.md (AI context that survives device switches)
- AI config files: CLAUDE.md, .cursorrules, .windsurfrules (not in git, local-only)
- Local env notes: API keys reference, server credentials (NOT actual secret values)
- Project notes: architecture decisions, dev diaries, planning docs

MULTI-DEVICE WORKFLOW:
  Laptop → push: create_dev_doc(title, content, local_path="~/.claude/.../MEMORY.md")
  Desktop → pull: pull_dev_docs() → automatically writes files to their local paths

CATEGORIES (subcategories under dev/):
- memory: Claude/AI memory files (~/.claude/projects/.../memory/)
- claude: CLAUDE.md files and Claude-specific configs
- cursor: .cursorrules files
- env: environment notes and config references
- docs: general project documentation

Set local_path to enable pull_dev_docs auto-sync to this machine.
 Endpoint: https://api.ainote.dev/api/mcp
- update_dev_doc - Update an existing dev document. Supports replace (default), append, or prepend modes. Optionally update the local_path for sync. Endpoint: https://api.ainote.dev/api/mcp
- pull_dev_docs - Restore all synced files to this device. Fetches every dev doc that has a local_path set and writes the content to that path on disk.

WHEN TO USE:
- First time setup on a new machine (desktop, laptop, etc.)
- After reinstalling macOS or setting up a fresh environment
- To restore Claude memory files, CLAUDE.md configs, and other local-only files

WHAT IT DOES:
1. Fetches all your dev docs that have local_path set
2. Creates any missing parent directories automatically
3. Writes the file content to each local_path on THIS machine
4. Reports success/failure for each file

TYPICAL FILES RESTORED:
- ~/.claude/projects/.../memory/MEMORY.md (AI context memory)
- ~/projects/*/CLAUDE.md (project-specific AI instructions)
- .cursorrules, .windsurfrules (editor AI configs)

Run this once after setting up ainote MCP on a new device.
 Endpoint: https://api.ainote.dev/api/mcp
- delete_dev_doc - Soft-delete a dev document by title or UUID. Reversible from trash. Pass `category` when multiple docs share the same title across subcategories (memory/claude/cursor/env/docs). Endpoint: https://api.ainote.dev/api/mcp
- list_dev_categories - List all subcategories under dev/ (memory, claude, cursor, env, docs, mcp, custom...) with document counts. Use to discover which categories exist before calling list_dev_docs with a category filter. Endpoint: https://api.ainote.dev/api/mcp
- signup_and_get_key - Create a new AI Note account and get an MCP API key. No authentication required. Use this if you don't have an account yet. Endpoint: https://api.ainote.dev/api/mcp
- login_and_get_key - Log in to an existing AI Note account and return an MCP API key. No prior authentication required. SIDE EFFECT: if the user has no MCP key yet, this call creates one (write to user.mcp_keys), so it is NOT idempotent and must be gated like other key-creation flows. Endpoint: https://api.ainote.dev/api/mcp
- get_setup_guide - Get instructions for setting up AI Note MCP in Claude Desktop, Cursor, or other MCP clients. No authentication required. Endpoint: https://api.ainote.dev/api/mcp
- vault_list - List the authenticated user's GitHub-backed vaults. Each entry includes slug, github_repo_full_name, sync status, indexed file count, and is_primary flag. Read-only. Pair with vault_clone to get the git clone URL or vault_sync to read/write vault files. Endpoint: https://api.ainote.dev/api/mcp
- vault_create - Create a new private vault as a GitHub repository under the user's account. Requires the user to have completed the GitHub App install flow first. Endpoint: https://api.ainote.dev/api/mcp
- vault_clone - Return the GitHub HTTPS clone URL for an existing vault. Authentication is via the user's normal GitHub credentials (PAT or gh CLI). Endpoint: https://api.ainote.dev/api/mcp
- vault_connect_status - Check whether the user has installed the ainote GitHub App. If connected, returns account_login + installation_id. If not, returns an install_url to surface to the user. Read-only; talks to GitHub API. Endpoint: https://api.ainote.dev/api/mcp
- vault_sync - Wrapper around vault file sync. action=list|pull|push to work against the primary vault. For push: WAF-bypass via `content_b64` or `content: '__B64__:...'` prefix (mirrors sync_push). Endpoint: https://api.ainote.dev/api/mcp
- sync_push - Push a markdown file into the primary vault. Optional CAS via base_sha to detect concurrent multi-PC writes (Layer 3 of multi-PC sync plan). WAF-bypass tip: large bodies (~10KB+) that get false-positive blocked at Cloudflare can be sent via `content_b64` (base64-encoded) OR `content` prefixed with `__B64__:` instead. Endpoint: https://api.ainote.dev/api/mcp
- sync_pull - Legacy alias for pulling files from the primary vault. Endpoint: https://api.ainote.dev/api/mcp
- sync_list - Legacy alias for listing files in the primary vault. Endpoint: https://api.ainote.dev/api/mcp
- sync_delete - Delete a file from the primary vault. Optional CAS via base_sha to detect concurrent multi-PC writes. Protected paths (global/memory/, global/skills/, global/planning/, global/claude-config/, handoffs/) require base_sha or explicit force:true (audited). Idempotent: deleting a non-existent path returns success with deleted:false. Endpoint: https://api.ainote.dev/api/mcp
- sync_merge - Compute a stateless 3-way merge for a vault file. Server runs `git merge-file --diff3 --stdout` over (base_text, local_text, current remote from file_indices) and returns the merged text plus the exact remote_sha it merged against. NO database mutation — to commit the result, follow up with sync_push(content=merged_text, base_sha=merged_against.remote_sha, resolves_conflict_id=conflict_id). Endpoint: https://api.ainote.dev/api/mcp
- sync_diff - Return the unified diff (and raw remote text) of a vault file. Useful for surfacing what `sync_merge` would conflict on, or for the client to render a `git diff` view before pushing. NO database mutation. Server has no history — base_text must be supplied by the caller if a 3-way view is needed; otherwise this returns remote_text only. Endpoint: https://api.ainote.dev/api/mcp
- sync_pending_conflicts - List unresolved vault_conflicts rows for the authenticated user's primary vault. Used by clients (e.g. SessionStart hook) to surface conflicts that need merge attention. Returns up to `limit` rows ordered by most recent first. Endpoint: https://api.ainote.dev/api/mcp
- sync_audit_layer5 - Record the result of a client-side Layer 5 codex review (sync.py merge gate) as a vault_events row. Body of the review is NOT stored — only an HMAC digest of the summary so operators can correlate without exposing review content. Opt-in: server skips writes (still returns success) unless ENV['AINOTE_LAYER5_AUDIT']='on' AND a versioned HMAC secret is configured. Used by the sync.py SessionStart hook + merge command to surface 'why was this blocked?' across multi-PC sessions. Endpoint: https://api.ainote.dev/api/mcp
- handoff_save - Save a session handoff note for cross-device / cross-session continuation. Stored at handoffs/{project}-{topic}-{YYYY-MM-DD}.txt in the user's primary vault. Use the optional `time` param (HHMM, KST) to disambiguate multiple handoffs saved on the same day — it is appended to the topic slug (e.g. topic='phase-d', time='1555' → handoffs/{project}-phase-d-1555-{date}.txt). Endpoint: https://api.ainote.dev/api/mcp
- handoff_list - List session handoff notes saved in the primary vault under handoffs/, most-recent first. v2 frontmatter fields (status / has_blockers / tags / task_type) can be filtered server-side and are exposed in each entry without fetching the body. Read-only: entries older than 7 days are filtered out of results (a daily server-side cleanup job permanently deletes them). Endpoint: https://api.ainote.dev/api/mcp
- handoff_get - Retrieve a session handoff by project + topic. If date is omitted, returns the most recent matching handoff. Pass `time` (HHMM, KST) to fetch a specific same-day save when multiple exist. Read-only: handoffs older than 7 days are not returned (a daily server-side cleanup job permanently deletes them). Endpoint: https://api.ainote.dev/api/mcp
- memory_search - Search your memory (dev docs / papers + vault markdown files) and get ranked snippets with IDs.

COST PRINCIPLE: search returns snippets only; call memory_get for full content.

MODES:
- keyword (default): hybrid keyword + semantic match across title/path/content
- latest_state: most recent memory, preferring entries saved with memory_type='state'
  (falls back to plain recency when no typed entries exist)

Returns { found: false, message: "no memory found" } when nothing matches — treat that
as a definitive empty signal and stop searching (do not guess).
 Endpoint: https://api.ainote.dev/api/mcp
- memory_get - Fetch the full content of ONE memory item found via memory_search. source='paper' requires `id`; source='vault_file' accepts `id` or `path`. Only the authenticated user's own items are accessible. Returns { found: false } when the item does not exist (or belongs to another user). Endpoint: https://api.ainote.dev/api/mcp

## Resources
- ainote://tasks/demo - Unauthenticated demo data — sign up via signup_and_get_key to see real tasks at ainote://tasks. MIME type: application/json
- ainote://categories/demo - Unauthenticated demo data — sign up via signup_and_get_key to see real categories at ainote://categories. MIME type: application/json

## Prompts
Not captured

## Metadata
- Owner: io.github.seunghan91
- Version: 1.3.2
- Runtime: Npm
- Transports: STDIO, HTTP
- License: Not captured
- Language: Not captured
- Stars: Not captured
- Updated: May 14, 2026
- Source: https://registry.modelcontextprotocol.io