Ainote MCP

MCP文档知识

提供方 未标注

文档知识 HTTP · 远程 未标注 社区 / 第三方
查看接入方式

全面解析Ainote MCPMCP Server的核心功能、安装配置和实用案例。作为顶级Model Context Protocol服务器,Ainote MCP能让AI助手访问实时数据、执行操作,为您提供更智能的工作体验和自动化解决方案。

一句话选型结论

按资料字段整理

Ainote MCP 属于文档知识类 MCP 服务器,HTTP · 远程,鉴权方式未标注,有可直接复制的远程端点配置。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式HTTP · 远程 鉴权未标注 部署方式远程部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

安装与配置

HTTP · 远程 未标注
连远程 HTTPS 端点,通常为 Streamable HTTP
npm install -g @ainote/mcp

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    确认你的客户端支持远程端点,并拿到服务地址。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • 远程端点依赖网络与服务方可用性,注意密钥与调用额度。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Ainote MCP当前 未标注 HTTP · 远程 远程部署 有 2026-05-17
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类文档知识本站按上游分类展示
连接方式HTTP · 远程连远程 HTTPS 端点,通常为 Streamable HTTP
鉴权方式未标注远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Node.js本地安装时用到的包标识与运行时
部署类型远程部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

26.6 KB
来自项目仓库与上游目录的原文,未做删改

AI Note MCP Server

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 - 전체 프로젝트 가이드 및 아키텍처 정보

Table of Contents

  • Access Methods
  • Features
  • Authentication
  • Prerequisites
  • Installation
  • Configuration
  • Usage
  • HTTP Endpoint
  • Available Tools
  • API Reference
  • Development
  • Troubleshooting
  • Contributing
  • License

Access Methods

AI Note MCP server is available through three transport options to cover different integration scenarios:

1. stdio Mode (This Package) - For Personal Use

  • Installation: npm install -g @ainote/mcp
  • Usage: Claude Desktop and other stdio-based MCP clients
  • Setup: Local installation with API key configuration
  • Best for: Individual users connecting their personal AI Note account to Claude Desktop

2. Local SSE Bridge (ChatGPT / MCP Apps)

  • Command: ainote-mcp-http
  • Protocol: Server-Sent Events (SSE) + JSON-RPC over HTTP POST
  • Usage: ChatGPT Model Context Protocol connectors, other SSE-capable MCP clients
  • Setup: Run locally alongside your browser; supports API key or (optional) OAuth bearer tokens
  • Best for: Users wanting to expose AI Note tools to ChatGPT without deploying infrastructure

3. Hosted HTTP Endpoint - For Platform Integration

  • URL: https://api.ainote.dev/api/mcp
  • Protocol: JSON-RPC 2.0 over HTTP
  • Usage: Platform integrations (Kakao PlayMCP, etc.)
  • 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:

1. Add to your MCP config (no API key yet)```json

{
"mcpServers": {
"ainote": {
"command": "npx",
"args": ["-y", "@ainote/mcp"]
}
}
}


### 2. Restart Claude Desktop

### 3. Ask Claude to sign you up

> "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.

### 4. Add the API key to your config```json
{
  "mcpServers": {
    "ainote": {
      "command": "npx",
      "args": ["-y", "@ainote/mcp"],
      "env": {
        "AINOTE_API_KEY": "<your-key-from-step-3>"
      }
    }
  }
}

5. Restart Claude Desktop again

Now all tools (tasks, dev docs, etc.) are available.

CLI Signup

You can also sign up directly from the terminal:```bash
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.```bash
# 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 ''. 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.

Quick start```bash

ainote-mcp login # browser-based, recommended
ainote-mcp whoami # verify current login
ainote-mcp logout # revoke + clear keychain


### How it works

`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`               |
| 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`).

### 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:```bash
$ 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.

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)

See docs/architecture/CLI_AUTH.md for the full protocol specification, sequence diagram, and security model.

Prerequisites

  • Node.js >= 18.0.0
  • npm or yarn
  • Claude Desktop with MCP support enabled

Installation

Option 1: Install from npm```bash

npm install -g @ainote/mcp


### Option 2: Install from source```bash
git clone https://github.com/ainote-dev/ainote-mcp.git
cd ainote-mcp-server
npm install

Update

Update from npm (Recommended)

To update to the latest version when installed via npm:```bash
npm update -g @ainote/mcp


Or to install a specific version:```bash
npm install -g @ainote/mcp@1.0.2

Update from source

If you installed from source:```bash
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:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Open the file and add the following JSON block inside the `mcpServers` object. **Replace `your-api-key-here` with your actual AI Note API key.**```json
{
  "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.```json
"env": {
"AINOTE_API_KEY": "your-api-key-here",
"AINOTE_API_URL": "https://your-custom-api-url.com"
}


### Step 3: Restart Claude Desktop

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


### Authentication```http
Authorization: Bearer YOUR_API_KEY

Request Format (JSON-RPC 2.0)```json

{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}


### Response Format```json
{
  "jsonrpc": "2.0",
  "result": {
    "tools": [...]
  },
  "id": 1
}

Supported Methods

  • ping - Health check
  • capabilities - Server capabilities
  • tools/list - List available tools
  • tools/call - Execute a specific tool

Platform Integration Examples

  • 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

Streaming Methods

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

Streaming Events```

event: progress
data: {"status": "starting", "total": 100}

event: data
data: {"type": "task", "data": {...}}

event: result
data: {"status": "success", "count": 100}


### 5. **Telegram Bot Integration** - Via Clawdbot
- **Setup Guide**: CLAWDBOT_SETUP.md
- **Tool**: mcporter for MCP server bridging
- **Usage**: Natural language task management in Telegram```bash
# Quick setup
npm install -g mcporter
mcporter call ainote.list_tasks

Local Development Bridge (ainote-mcp-http)

Run the bundled HTTP/SSE bridge when you need a local endpoint for ChatGPT or other MCP clients that speak SSE:```bash
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 `sessionId`
- `POST /messages?sessionId=...` – receives JSON-RPC payloads from the client
- `GET /health` – simple health probe for monitoring

#### Configuration

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.

## Available Tools

### list_tasks

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 content
- `is_important` (optional): Filter important tasks only

**Location & Category:**
- `location` (optional): Filter by location (partial match, e.g., "여의도")
- `category_id` (optional): Filter by category UUID

**Date Range Filters:**
- `due_date_start` / `due_date_end`: Filter by due date range
- `completed_date_start` / `completed_date_end`: Filter by completion date
- `created_date_start` / `created_date_end`: Filter by creation date

**Special Filters:**
- `overdue` (optional): Filter overdue incomplete tasks
- `due_today` (optional): Filter tasks due today
- `has_notification` (optional): Filter by notification status

**Sorting:**
- `sort_by` (optional): Sort field - "due_date", "created_at", "completed_at", "updated_at", "is_important"
- `sort_order` (optional): Sort direction - "asc" or "desc"

### create_task

Create a new task in AI Note.

**Parameters:**
- `content` (required): Task description
- `is_important` (optional): Mark as important (boolean)
- `due_date` (optional): Due date in ISO format
- `category_id` (optional): Category ID to assign

### update_task

Update an existing task.

**Parameters:**
- `id` (required): Task ID
- `content` (optional): New task content
- `is_important` (optional): Update important status
- `completed_at` (optional): Mark as completed (ISO format) or null to uncomplete

### delete_task

Soft delete a task.

**Parameters:**
- `id` (required): Task ID to delete

### list_categories

List all available categories.

**Parameters:** None

---

### Dev Doc Tools (v1.1.0+)

Manage AI coding tool configuration files and dev documents centrally. All docs are organized under the `dev/` category hierarchy.

#### list_dev_docs

List dev documents with optional filtering.

**Parameters:**
- `category` (optional): Subcategory filter (claude, cursor, windsurf, copilot, docs)
- `search` (optional): Search keyword in document title
- `content_type` (optional): Filter by type - "markdown", "json", "yaml", "text"

#### get_dev_doc

Get a single dev document by title or id.

**Parameters:**
- `title` or `id` (one required): Document identifier
- `category` (optional): Subcategory to disambiguate title
- `include_versions` (optional): Include version history

#### create_dev_doc

Create a new dev document under `dev/` category.

**Parameters:**
- `title` (required): Document title (e.g., "project-a-claude.md")
- `content` (required): Document content
- `category` (optional): Subcategory (default: "docs")
- `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()

Session Handoffs (cross-session / cross-device continuation)

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)```json

{
"mcpServers": {
"ainote": {
"command": "npx",
"args": ["-y", "@ainote/mcp"],
"env": { "AINOTE_API_KEY": "..." }
}
}
}


### Claude Code (direct HTTP — recommended for full feature set)```json
{
  "mcpServers": {
    "ainote": {
      "type": "http",
      "url": "https://api.ainote.dev/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 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 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```bash

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

1. Update your Claude Desktop config to point to your local development server
2. Set environment variables for testing
3. Restart Claude Desktop
4. 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

  1. "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

  2. "Connection refused" error
    - Verify the API URL is correct
    - Check network connectivity
    - Ensure the AI Note API server is running

  3. "Tool not found" error
    - Restart Claude Desktop after configuration changes
    - Verify the MCP server is properly configured in Claude Desktop

  4. 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:bash export DEBUG=mcp:*

Contributing

We welcome contributions! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. 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.

Support

  • 📧 Email: support@ainote.dev
  • 🐛 Issues: GitHub Issues
  • 💬 Discord: Join our community

Acknowledgments

  • Built with Model Context Protocol SDK
  • Powered by AI Note
  • Made for Claude Desktop

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Ainote MCP 怎么安装?

在客户端按下面的安装命令接入:npm install -g @ainote/mcp。装完在客户端配置里引用同一个包或端点。

Ainote MCP 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

Ainote MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Ainote MCP 需要 API Key 吗?

资料没有标注鉴权方式,是否需要密钥取决于服务本身,接入前按官方文档确认。

Ainote MCP 能提供哪些能力?

资料显示能力标签包括 自然语言、任务管理、JavaScript、HTTP、文档处理。具体工具清单以官方文档为准。

Ainote MCP 需要什么运行环境?

运行时为 Node.js;属于远程端点,不需要在本地装运行时。

Ainote MCP 是本地还是远程?

它是远程端点,连服务地址即可。传输方式为HTTP · 远程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。