The AI Note MCP Server enables AI assistants to seamlessly manage your AI Note task management system through natural language commands.
Core Capabilities:
Task Management: Create, update, soft delete, and list tasks with support for content, importance levels, due dates (ISO format), completion status, and category assignments
Advanced Filtering: Search tasks by content keywords, filter by status (pending/completed), and limit results
Category Management: List available categories and organize tasks accordingly
Priority System: Mark tasks as important and manage priority levels
Integration Methods:
stdio Mode: Direct integration with Claude Desktop and other stdio-based MCP clients
Local SSE Bridge: Expose tools to ChatGPT and SSE-capable clients without deploying infrastructure
Hosted HTTP Endpoint: Platform integrations (e.g., Kakao PlayMCP) and custom applications requiring direct API access
Security & Compatibility:
API key authentication with optional OAuth bearer token support
Cross-platform compatibility with Claude Desktop, ChatGPT, and other MCP-compatible platforms
Provides a Node.js-based MCP server implementation for AI Note integration, supporting task management with categories, search, priority management, and due date features.
Allows installation and distribution of the AI Note MCP server package through npm registry, making it easily accessible for Claude Desktop users.
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
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/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
🏷️ Category Support: Organize tasks with categories
🔍 Advanced Search: Search tasks by content, status, and more
⭐ Priority Management: Mark tasks as important
📅 Due Date Support: Set and manage task due dates
🔒 Secure API Integration: Uses API key authentication for secure access
Prerequisites
Node.js >= 18.0.0
npm or yarn
AI Note API access (API key required)
Claude Desktop with MCP support enabled
Installation
Option 1: Install from npm
Option 2: Install from source
Update
Update from npm (Recommended)
To update to the latest version when installed via npm:
Or to install a specific version:
Update from source
If you installed from source:
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
Note: If you need to connect to a self-hosted or different AI Note server, you can add the
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
HTTP Endpoint
For platform integrations and services that prefer HTTP over stdio, AI Note provides a direct HTTP endpoint:
Endpoint URL
Authentication
Request Format (JSON-RPC 2.0)
Response Format
Supported Methods
ping
- Health checkcapabilities
- Server capabilitiestools/list
- List available toolstools/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.
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:
By default the server listens on http://localhost:3030
and exposes two endpoints:
GET /sse
– establishes the SSE stream and returns thesessionId
POST /messages?sessionId=...
– receives JSON-RPC payloads from the clientGET /health
– simple health probe for monitoring
Configuration
Environment variable | Description | Default |
| API key used for MCP key authentication | required |
| Target AI Note API base URL |
|
| Local port for the SSE server |
|
| Comma-separated list of allowed browser origins | any |
| Comma-separated list of allowed
headers | any |
| Set to
to allow Bearer tokens (OAuth) |
|
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 filtering options.
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
create_task
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 assign
update_task
Update 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 uncomplete
delete_task
Soft delete a task.
Parameters:
id
(required): Task ID to delete
list_categories
List all available categories.
Parameters: None
API Reference
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 categories
All requests require authentication via the Authorization
header with your API key.
Development
Running Locally
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
Troubleshooting
Common Issues
"API key not found" error
Ensure
AINOTE_API_KEY
is set in your environment or Claude configCheck 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:
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.
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
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A Model Context Protocol server that connects Claude Desktop to AI Note task management, enabling task creation, updates and management through natural language conversations.
Related MCP Servers
- AsecurityAlicenseAqualityModel Context Protocol server for Task Management. This allows Claude Desktop (or any MCP client) to manage and execute tasks in a queue-based system.Last updated -10329194MIT License
- AsecurityFlicenseAqualityA Model Context Protocol server that connects Claude and other AI assistants to your Notion workspace, allowing AIs to interact with databases, pages, and blocks.Last updated -12011
- AsecurityAlicenseAqualityA Model Context Protocol server that allows Claude Desktop to manage and execute tasks in a queue-based system, supporting planning, execution, and completion phases.Last updated -103296MIT License
302AI BrowserUse MCP Serverofficial
AsecurityAlicenseAqualityA Model Context Protocol server that enables Claude Desktop to browse the web, likely allowing the AI to access and interact with web content.Last updated -2175MIT License