A Model Context Protocol (MCP) server that connects AI assistants to your AI Note task management system. This package enables direct interaction with your AI Note tasks through natural language conversations in Claude Desktop and other MCP-compatible platforms.
MCP server for AI Note - Tasks, Dev Docs, and multi-device file sync (CLAUDE.md, memory files, Cursor rules, Windsurf rules)
Setup: No installation required, direct API access
Best for: Third-party platforms and services integrating AI Note functionality
All transports expose the same tool catalog. Choose the option that matches your hosting model and client capabilities.
Features
📝 Task Management: Create, update, delete, and list tasks directly from Claude Desktop
📄 Dev Docs: Manage CLAUDE.md, Cursor rules, Windsurf rules, and dev documents centrally via MCP
🗂️ Dev Category Hierarchy: Auto-organized under dev/ with subcategories (claude, cursor, windsurf, copilot, docs, skills, agents, commands, hooks, mcp)
🔄 Claude Environment Sync: Push/pull ~/.claude/ skills, agents, commands, hooks across machines (macOS/WSL/Linux)
🔐 End-to-End Encryption: mcp category (mcpServers + API keys) auto-encrypted client-side with age; server never sees plaintext
🪪 OS Keychain Integration: Per-machine age identity stored in macOS Keychain / libsecret / Credential Manager (file fallback supported)
🤝 Session Handoffs: handoff_save / handoff_list / handoff_get with optional time: HHMM for same-day disambiguation — saved under the primary vault, auto-purged after 7 days
📦 Multi-Device File Sync: sync_push / sync_pull / sync_list push markdown notes into the user's git-backed primary vault — works across macOS, Linux, iOS shortcuts
🏛️ GitHub-Backed Vaults: vault_create / vault_clone / vault_sync provision a private GitHub repo per vault; ainote indexes contents but never proxies git traffic
🛡️ MCP Tool Annotations: Every tool advertises readOnlyHint / destructiveHint / idempotentHint / openWorldHint so autonomous agent runtimes can gate destructive calls
🏷️ Category Support: Organize tasks with categories
🔍 Advanced Filtering: 18+ filter options including date ranges, location, overdue tasks
⭐ Priority Management: Mark tasks as important
📅 Smart Due Dates: Human-readable format with relative time (e.g., '26.1.25 14:30 - 오늘)
🔒 Dual Authentication: Support for both User API Key (24-char) and MCP Key (64-char)
📊 Usage Tracking: Automatic API usage statistics per MCP key
🌊 Streaming API: Real-time streaming for bulk operations and large datasets
🤖 Bot Integration: Telegram bot support via Clawdbot + mcporter
Quick Start (No Account Needed)
You can start using AI Note MCP without an existing account. The MCP server includes onboarding tools that let you sign up and get an API key directly from Claude:
Now all tools (tasks, dev docs, etc.) are available.
CLI Signup
You can also sign up directly from the terminal:
npx @ainote/mcp signup
This will interactively ask for email, password, and name, then return your MCP API key.
CLI Tool Invocation (call)
Run any of the 26 ainote tools directly from the shell — no Claude / Cursor / MCP host required. Useful for scripts, alfred / raycast workflows, automation, and one-off queries.
# List all tasks due today
npx @ainote/mcp call list_tasks --due_today=true
# Save a handoff (JSON form)
npx @ainote/mcp call handoff_save \
--json '{"project":"demo","topic":"poc","content":"..."}'
# Get a handoff
npx @ainote/mcp call handoff_get --project=demo --topic=poc
# Read a resource URI as JSON (load all tasks at once)
npx @ainote/mcp call list_tasks --limit=500
Flag parsing: --key=value is JSON.parse-d (numbers/booleans/null/arrays/objects work directly; raw strings fall back). Pass the entire arguments object via --json '<obj>'. Add --raw for the full JSON-RPC envelope.
Auth resolution order: AINOTE_API_KEY env var → OS keychain (from ainote-mcp login).
Onboarding MCP Tools
These tools also work inside Claude (no API key needed):
Tool
Description
signup_and_get_key
Create account + get MCP key
login_and_get_key
Login + get MCP key (existing account)
get_setup_guide
Setup instructions
Authentication
The CLI supports browser-based login as a more secure alternative to manually pasting API keys into your MCP config. Tokens and the MCP key are stored in the OS keychain.
ainote-mcp login runs an RFC 8628 OAuth 2.0 Device Authorization Grant. The CLI generates a PKCE pair locally, opens your browser to sign in via the AI Note web app, and polls the backend until you approve. On success it stores an access token, a refresh token, and an MCP key in the OS keychain. The default MCP stdio mode automatically uses the stored MCP key — no AINOTE_API_KEY env var needed.
Storage locations
OS
Location
macOS
Keychain Access — service @ainote/cli
Linux
libsecret (gnome-keyring / kwallet) — service @ainote/cli
The fallback file is only used when no system keychain is available (e.g. headless servers without libsecret).
CLI flags
--scope=mcp,read,write — comma-separated scopes requested for the token (default: mcp,read,write)
--no-browser — print the verification URL instead of auto-opening a browser (use this on SSH/CI)
Environment overrides
AINOTE_API_URL — backend URL (default https://ainote-5muq.onrender.com; login, call, and the MCP server all share it, since stored credentials are keyed by host)
AINOTE_API_KEY — pre-provisioned MCP key. When set, the login flow is bypassed entirely and this key is used as-is.
Headless / CI usage
For SSH sessions, devcontainers, or CI runners that cannot open a browser, use --no-browser. The CLI will print a short user code and a verification URL; open the URL on any device (laptop, phone) signed in to your AI Note account, approve the request, then return to the terminal:
$ ainote-mcp login --no-browser
Open this URL in any browser:
https://ainote.dev/oauth/cli/device?user_code=BCDF-GHJK
Waiting for approval...
✓ Logged in as [email protected]
After login, subsequent invocations (ainote-mcp, ainote-mcp whoami) work normally with no further interaction.
Troubleshooting
Symptom
Fix
LOGIN_HINT error on any subcommand
Run ainote-mcp login
macOS Keychain prompt every run
Open Keychain Access, find @ainote/cli, set access control to "Always allow" for node
Browser does not open
Re-run with --no-browser and copy the URL manually
Persistent 401 after login
Tokens were revoked server-side. Run ainote-mcp login again
libsecret not available on Linux
Install gnome-keyring / libsecret-1-0, or rely on the file fallback (still encrypted at-rest by the OS)
cd ainote-mcp-server
git pull origin main
npm install
After updating, restart Claude Desktop to load the new version.
Configuration
To connect the MCP server with Claude Desktop, follow these steps.
Step 1: Get your AI Note API Key
You need an API key from your AI Note account to allow Claude to access your tasks. You can find or generate your API key in the AI Note app's settings screen.
Step 2: Configure Claude Desktop
Add the ainote-mcp server to your Claude Desktop configuration file. This file is located at:
After saving the configuration file, restart Claude Desktop completely. The new MCP server will be loaded, and you can start managing your AI Note tasks through Claude.
Usage
Once configured, you can interact with your AI Note tasks through Claude:
Example Conversations
You: "Show me my pending tasks"
Claude: I'll retrieve your pending tasks from AI Note...
You: "Create a new task to review the quarterly report by Friday"
Claude: I'll create that task for you with a due date set for Friday...
You: "Mark task ID 123 as completed"
Claude: I'll mark that task as completed...
HTTP Endpoint
For platform integrations and services that prefer HTTP over stdio, AI Note provides a direct HTTP endpoint:
Endpoint URL
POST https://api.ainote.dev/api/mcp
Content-Type: application/json
Kakao PlayMCP: Use the HTTP endpoint for seamless integration
Custom Applications: Build your own MCP client using the HTTP API
Enterprise Solutions: Direct server-to-server communication
This HTTP endpoint provides identical functionality to the stdio version, making AI Note MCP accessible to a broader range of platforms and integration scenarios.
4. Streaming API - For Large Data Operations
URL: POST https://api.ainote.dev/api/mcp/stream
Protocol: Server-Sent Events (SSE)
Usage: Bulk operations, large task lists, real-time progress
Best for: Applications that need to handle large datasets or show progress indicators
content_type (optional): Auto-detected from title extension
update_dev_doc
Update a dev document with replace, append, or prepend modes.
Parameters:
title or id (one required): Document identifier
content (required): New content
mode (optional): "replace" (default), "append", or "prepend"
delete_dev_doc
Soft delete a dev document.
Parameters:
title or id (one required): Document identifier
list_dev_categories
List all subcategories under dev/ with document counts.
Parameters: None
Example: Store CLAUDE.md in ainote
You: "Save this project's CLAUDE.md content to ainote"
Claude: I'll create a dev doc in the claude category...
→ create_dev_doc(title: "myproject-claude.md", content: "...", category: "claude")
You: "Update my cursor rules in ainote"
Claude: I'll update the cursor rules doc...
→ update_dev_doc(title: "api-rules.mdc", category: "cursor", content: "...")
You: "Show me all my dev docs"
Claude: I'll list all documents under dev/...
→ list_dev_docs()
Save a self-contained handoff note when the context window fills up or when you need to continue on another machine. Stored in the user's primary vault under handoffs/, auto-purged after 7 days.
Tool
Purpose
handoff_save
Write a handoff (project, topic, content, optional date, optional time HHMM for same-day disambiguation)
handoff_list
Most-recent-first list, optionally filtered by project. ⚠️ Triggers the 7-day stale purge as a side effect
handoff_get
Fetch by project + topic (+ optional date/time). Returns latest if date omitted. Same purge side effect
You: "Save a handoff for the logi-phase4 work I'm wrapping up"
Claude: → handoff_save({project: "logi", topic: "phase4", time: "1555", content: "..."})
Stored at handoffs/logi-phase4-1555-2026-05-14.txt
(later, on the laptop):
You: "Pick up the logi-phase4 handoff"
Claude: → handoff_get({project: "logi", topic: "phase4"})
Multi-Device File Sync (sync_* / vault_sync)
sync_push / sync_pull / sync_list operate on the user's git-backed primary vault. vault_sync is the unified entrypoint that accepts an action: list|pull|push argument.
Tool
Purpose
sync_push
Push a markdown note (path + content) into the vault repo
sync_pull
Read a markdown note from the vault by path
sync_list
Enumerate vault paths (optionally filtered)
vault_sync
Unified wrapper around the above three
GitHub-Backed Vaults
Tool
Purpose
vault_list
List the user's vaults + sync status + indexed file counts
vault_create
Create a new private vault as a GitHub repo (requires the ainote GitHub App install)
vault_clone
Return the git clone URL for an existing vault. ainote does not proxy git traffic — use your usual GitHub credentials
vault_connect_status
Check whether the ainote GitHub App is installed for this user; returns an install URL otherwise
Annotations Reference
Every tool advertises four MCP-spec annotations on tools/list so autonomous agent runtimes can reason about safety:
Hint
Meaning
Agent action
readOnlyHint: true
Tool does not mutate any server state
Safe to call without consent gates
destructiveHint: true
Tool deletes / overwrites / purges state
Require explicit user consent or transaction boundary
idempotentHint: true
Repeating the call with same args ends in the same state
Safe to retry on timeout / network error
openWorldHint: true
Tool reaches an external system (GitHub, SMTP, third-party)
Outcomes may be non-deterministic; cache cautiously
Notable annotations:
handoff_list / handoff_get are marked destructiveHint: true because they run a 7-day stale-handoff purge on every call.
login_and_get_key is marked readOnlyHint: false because it creates a default MCP key when the user has none.
vault_sync is conservatively destructiveHint: true because action=push with empty content can delete an indexed file.
The live tools/list response is the source of truth for these annotations.
Agent Compatibility
ainote MCP works with any client that speaks Model Context Protocol over stdio or HTTP. Tested setups:
Claude Desktop / Claude Code (stdio via this npm package)
The type: "http" field is required — without it, Claude Code's user-level MCP loader silently rejects the entire mcpServers block.
Cursor / Windsurf (stdio)
Same as Claude Desktop config — both editors accept the command + args + env shape.
ChatGPT / OpenAI Custom GPTs
Use the hosted HTTP endpoint via OpenAI Connectors or Custom GPT Actions. The MCP JSON-RPC body works as a regular HTTPS POST. An OpenAPI 3.1 mirror of the tool surface is planned (see docs/todo/AGENT_INTEROP_ROADMAP_2026.md Phase 1.4).
LangChain / LangGraph
Wrap the HTTP endpoint as a remote tool. Pass Authorization: McpKey <YOUR_MCP_KEY> and POST JSON-RPC requests. Tool definitions can be discovered via tools/list.
API Reference
The MCP server communicates with the AI Note API using the following endpoints:
GET /api/mcp/tasks - List tasks
POST /api/mcp/tasks - Create task
PUT /api/mcp/tasks/:id - Update task
DELETE /api/mcp/tasks/:id - Delete task
GET /api/mcp/categories - List categories
All requests require authentication via the Authorization header with your API key.
Development
Running Locally
# Clone the repository
git clone https://github.com/ainote-dev/ainote-mcp.git
cd ainote-mcp-server
# Install dependencies
npm install
# Run the server
npm start
Testing with Claude Desktop
Update your Claude Desktop config to point to your local development server
Set environment variables for testing
Restart Claude Desktop
Check the MCP connection status in Claude Desktop settings
Project Structure
ainote-mcp-server/
├── index.js # Main server implementation
├── package.json # Package configuration
├── README.md # English documentation
├── README-ko.md # Korean documentation
└── LICENSE # MIT license
Troubleshooting
Common Issues
"API key not found" error
Ensure AINOTE_API_KEY is set in your environment or Claude config
Check that the API key is valid and has proper permissions
"Connection refused" error
Verify the API URL is correct
Check network connectivity
Ensure the AI Note API server is running
"Tool not found" error
Restart Claude Desktop after configuration changes
Verify the MCP server is properly configured in Claude Desktop
Tasks not appearing
Check API key permissions
Verify you're querying the correct status (pending/completed)
Try using the search parameter
Debug Mode
To enable debug logging:
export DEBUG=mcp:*
Contributing
We welcome contributions! Please follow these steps:
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
Development Guidelines
Follow the existing code style
Add tests for new features
Update documentation as needed
Ensure all tests pass before submitting PR
License
This project is licensed under the MIT License - see the LICENSE file for details.