@ainote/mcp
Advanced tools
MCP server for AI Note - Tasks, Dev Docs, and multi-device file sync (CLAUDE.md, memory files, Cursor rules, Windsurf rules)
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.
ð Complete Project Guide - ė ėēī íëĄė íļ ę°ėīë ë° ėíĪí ėē ė ëģī
AI Note MCP server is available through three transport options to cover different integration scenarios:
npm install -g @ainote/mcpainote-mcp-httphttps://api.ainote.dev/api/mcpAll transports expose the same tool catalog. Choose the option that matches your hosting model and client capabilities.
dev/ with subcategories (claude, cursor, windsurf, copilot, docs, skills, agents, commands, hooks, mcp)~/.claude/ skills, agents, commands, hooks across machines (macOS/WSL/Linux)mcp category (mcpServers + API keys) auto-encrypted client-side with age; server never sees plaintexthandoff_save / handoff_list / handoff_get with optional time: HHMM for same-day disambiguation â saved under the primary vault, auto-purged after 7 dayssync_push / sync_pull / sync_list push markdown notes into the user's git-backed primary vault â works across macOS, Linux, iOS shortcutsvault_create / vault_clone / vault_sync provision a private GitHub repo per vault; ainote indexes contents but never proxies git trafficreadOnlyHint / destructiveHint / idempotentHint / openWorldHint so autonomous agent runtimes can gate destructive calls'26.1.25 14:30 - ėĪë)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:
{
"mcpServers": {
"ainote": {
"command": "npx",
"args": ["-y", "@ainote/mcp"]
}
}
}
"Sign me up for AI Note with email user@example.com and password mypassword123"
Claude will call the signup_and_get_key tool and return your MCP API key.
{
"mcpServers": {
"ainote": {
"command": "npx",
"args": ["-y", "@ainote/mcp"],
"env": {
"AINOTE_API_KEY": "<your-key-from-step-3>"
}
}
}
}
Now all tools (tasks, dev docs, etc.) are available.
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.
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 |
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 # browser-based, recommended
ainote-mcp whoami # verify current login
ainote-mcp logout # revoke + clear 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.
| OS | Location |
|---|---|
| macOS | Keychain Access â service @ainote/cli |
| Linux | libsecret (gnome-keyring / kwallet) â service @ainote/cli |
| Windows | Credential Manager â target @ainote/cli |
| Fallback | ${XDG_CONFIG_HOME:-~/.config}/ainote/credentials.json (mode 0600) |
The fallback file is only used when no system keychain is available (e.g. headless servers without libsecret).
--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)AINOTE_API_URL â backend URL (default https://ainote-5muq.onrender.com)AINOTE_API_KEY â pre-provisioned MCP key. When set, the login flow is bypassed entirely and this key is used as-is.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 you@example.com
After login, subsequent invocations (ainote-mcp, ainote-mcp whoami) work normally with no further interaction.
| 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) |
See docs/architecture/CLI_AUTH.md for the full protocol specification, sequence diagram, and security model.
npm install -g @ainote/mcp
git clone https://github.com/ainote-dev/ainote-mcp.git
cd ainote-mcp-server
npm install
To update to the latest version when installed via npm:
npm update -g @ainote/mcp
Or to install a specific version:
npm install -g @ainote/mcp@1.0.2
If you installed from source:
cd ainote-mcp-server
git pull origin main
npm install
After updating, restart Claude Desktop to load the new version.
To connect the MCP server with Claude Desktop, follow these steps.
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.
Add the ainote-mcp server to your Claude Desktop configuration file. This file is located at:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonOpen the file and add the following JSON block inside the mcpServers object. Replace your-api-key-here with your actual AI Note API key.
{
"mcpServers": {
"ainote": {
"command": "ainote-mcp",
"env": {
"AINOTE_API_KEY": "your-api-key-here"
}
}
}
}
Note: If you need to connect to a self-hosted or different AI Note server, you can add the AINOTE_API_URL environment variable as well.
"env": {
"AINOTE_API_KEY": "your-api-key-here",
"AINOTE_API_URL": "https://your-custom-api-url.com"
}
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.
Once configured, you can interact with your AI Note tasks through Claude:
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...
For platform integrations and services that prefer HTTP over stdio, AI Note provides a direct HTTP endpoint:
POST https://api.ainote.dev/api/mcp
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}
{
"jsonrpc": "2.0",
"result": {
"tools": [...]
},
"id": 1
}
ping - Health checkcapabilities - Server capabilitiestools/list - List available toolstools/call - Execute a specific toolThis HTTP endpoint provides identical functionality to the stdio version, making AI Note MCP accessible to a broader range of platforms and integration scenarios.
POST https://api.ainote.dev/api/mcp/stream| Method | Description |
|---|---|
tasks/list | Stream task list with filters |
tasks/create | Create single task with progress |
tasks/analyze | Get task statistics and insights |
tasks/bulk_update | Update multiple tasks with progress |
tasks/bulk_create | Create up to 1000 tasks at once |
event: progress
data: {"status": "starting", "total": 100}
event: data
data: {"type": "task", "data": {...}}
event: result
data: {"status": "success", "count": 100}
# Quick setup
npm install -g mcporter
mcporter call ainote.list_tasks
ainote-mcp-http)Run the bundled HTTP/SSE bridge when you need a local endpoint for ChatGPT or other MCP clients that speak SSE:
ainote-mcp-http
By default the server listens on http://localhost:3030 and exposes two endpoints:
GET /sse â establishes the SSE stream and returns the sessionIdPOST /messages?sessionId=... â receives JSON-RPC payloads from the clientGET /health â simple health probe for monitoring| Environment variable | Description | Default |
|---|---|---|
AINOTE_API_KEY | API key used for MCP key authentication | required |
AINOTE_API_URL | Target AI Note API base URL | https://ainote-5muq.onrender.com |
AINOTE_MCP_HTTP_PORT | Local port for the SSE server | 3030 |
AINOTE_MCP_ALLOWED_ORIGINS | Comma-separated list of allowed browser origins | any |
AINOTE_MCP_ALLOWED_HOSTS | Comma-separated list of allowed Host headers | any |
AINOTE_ENABLE_OAUTH_AUTH | Set to true to allow Bearer tokens (OAuth) | false |
When OAuth is enabled the server expects Authorization: Bearer ... headers from the client and forwards them to the AI Note API.
List tasks from AI Note with advanced filtering options.
Basic Parameters:
status (optional): Filter by status - "pending" or "completed"limit (optional): Maximum number of tasks (default: 25, max: 500)search (optional): Search keyword in task contentis_important (optional): Filter important tasks onlyLocation & Category:
location (optional): Filter by location (partial match, e.g., "ėŽėë")category_id (optional): Filter by category UUIDDate Range Filters:
due_date_start / due_date_end: Filter by due date rangecompleted_date_start / completed_date_end: Filter by completion datecreated_date_start / created_date_end: Filter by creation dateSpecial Filters:
overdue (optional): Filter overdue incomplete tasksdue_today (optional): Filter tasks due todayhas_notification (optional): Filter by notification statusSorting:
sort_by (optional): Sort field - "due_date", "created_at", "completed_at", "updated_at", "is_important"sort_order (optional): Sort direction - "asc" or "desc"Create a new task in AI Note.
Parameters:
content (required): Task descriptionis_important (optional): Mark as important (boolean)due_date (optional): Due date in ISO formatcategory_id (optional): Category ID to assignUpdate an existing task.
Parameters:
id (required): Task IDcontent (optional): New task contentis_important (optional): Update important statuscompleted_at (optional): Mark as completed (ISO format) or null to uncompleteSoft delete a task.
Parameters:
id (required): Task ID to deleteList all available categories.
Parameters: None
Manage AI coding tool configuration files and dev documents centrally. All docs are organized under the dev/ category hierarchy.
List dev documents with optional filtering.
Parameters:
category (optional): Subcategory filter (claude, cursor, windsurf, copilot, docs)search (optional): Search keyword in document titlecontent_type (optional): Filter by type - "markdown", "json", "yaml", "text"Get a single dev document by title or id.
Parameters:
title or id (one required): Document identifiercategory (optional): Subcategory to disambiguate titleinclude_versions (optional): Include version historyCreate a new dev document under dev/ category.
Parameters:
title (required): Document title (e.g., "project-a-claude.md")content (required): Document contentcategory (optional): Subcategory (default: "docs")content_type (optional): Auto-detected from title extensionUpdate a dev document with replace, append, or prepend modes.
Parameters:
title or id (one required): Document identifiercontent (required): New contentmode (optional): "replace" (default), "append", or "prepend"Soft delete a dev document.
Parameters:
title or id (one required): Document identifierList all subcategories under dev/ with document counts.
Parameters: None
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"})
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 |
| 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 |
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.See the source-of-truth mapping at docs/todo/MCP_TOOL_ANNOTATIONS_MAPPING.md in the ainote repo.
ainote MCP works with any client that speaks Model Context Protocol over stdio or HTTP. Tested setups:
{
"mcpServers": {
"ainote": {
"command": "npx",
"args": ["-y", "@ainote/mcp"],
"env": { "AINOTE_API_KEY": "..." }
}
}
}
{
"mcpServers": {
"ainote": {
"type": "http",
"url": "https://ainote-5muq.onrender.com/api/mcp",
"headers": { "Authorization": "McpKey <YOUR_MCP_KEY>" }
}
}
}
The
type: "http"field is required â without it, Claude Code's user-level MCP loader silently rejects the entiremcpServersblock.
Same as Claude Desktop config â both editors accept the command + args + env shape.
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).
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.
The MCP server communicates with the AI Note API using the following endpoints:
GET /api/mcp/tasks - List tasksPOST /api/mcp/tasks - Create taskPUT /api/mcp/tasks/:id - Update taskDELETE /api/mcp/tasks/:id - Delete taskGET /api/mcp/categories - List categoriesAll requests require authentication via the Authorization header with your API key.
# 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
ainote-mcp-server/
âââ index.js # Main server implementation
âââ package.json # Package configuration
âââ README.md # English documentation
âââ README-ko.md # Korean documentation
âââ LICENSE # MIT license
"API key not found" error
AINOTE_API_KEY is set in your environment or Claude config"Connection refused" error
"Tool not found" error
Tasks not appearing
To enable debug logging:
export DEBUG=mcp:*
We welcome contributions! Please follow these steps:
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.
FAQs
MCP server for AI Note - Tasks, Dev Docs, and multi-device file sync (CLAUDE.md, memory files, Cursor rules, Windsurf rules)
The npm package @ainote/mcp receives a total of 27 weekly downloads. As such, @ainote/mcp popularity was classified as not popular.
We found that @ainote/mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.