AI Note MCP Server

# AI Note MCP Server [](https://badge.fury.io/js/%40ainote%2Fmcp-server) [](https://opensource.org/licenses/MIT) 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](../docs/PROJECT_GUIDE.md)** - 전체 프로젝트 가이드 및 아키텍처 정보 ## Table of Contents - [Access Methods](#access-methods) - [Features](#features) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Configuration](#configuration) - [Usage](#usage) - [HTTP Endpoint](#http-endpoint) - [Available Tools](#available-tools) - [API Reference](#api-reference) - [Development](#development) - [Troubleshooting](#troubleshooting) - [Contributing](#contributing) - [License](#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/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 ```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/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. ### 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 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 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 ## 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](LICENSE) file for details. ## Support - 📧 Email: support@ainote.dev - 🐛 Issues: [GitHub Issues](https://github.com/ainote-dev/ainote-mcp/issues) - 💬 Discord: [Join our community](https://discord.gg/ainote) ## Acknowledgments - Built with [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk) - Powered by [AI Note](https://ainote.dev) - Made for [Claude Desktop](https://claude.ai/desktop)