JinDaGe - noteplan-mcp MCP Details

article

README

🚀 NotePlan MCP 服务器

NotePlan MCP 服务器是一个消息控制协议（MCP）服务器，它使 Claude Desktop 能够与 NotePlan.co 进行交互。该服务器实现了 Claude 与 NotePlan 笔记的无缝集成，让你可以在 Claude 对话中直接查询、搜索、创建和更新笔记。

🚀 快速开始

安装依赖：
```
npm install
```
构建项目：
```
npm run build
```
测试服务器：
```
npm start
```
你应该会看到："NotePlan MCP server running on stdio"
配置 Claude Desktop（详见下面的详细设置）

✨ 主要特性

读取笔记：获取所有笔记、通过 ID 获取特定笔记，或获取特定文件夹中的笔记
搜索：对所有笔记进行全文搜索
创建笔记：创建带有标题、内容和文件夹组织的新笔记
每日笔记：创建和管理具有自动日期格式的每日笔记
更新笔记：修改现有笔记的标题和内容
文件夹组织：按文件夹组织和过滤笔记

📦 安装指南

选项 1：从 GitHub 克隆

git clone https://github.com/bscott/noteplan-mcp.git
cd noteplan-mcp
npm install

选项 2：作为 NPM 包安装（即将推出）

npm install -g noteplan-mcp

📚 详细文档

Claude Desktop 配置

要在 Claude Desktop 中使用此 MCP 服务器，请将以下配置添加到你的 Claude Desktop 配置文件中：

步骤 1：定位配置文件

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

步骤 2：添加 NotePlan MCP 服务器

将以下配置添加到你的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "noteplan": {
      "command": "node",
      "args": ["/absolute/path/to/noteplan-mcp/build/index.js"],
      "cwd": "/absolute/path/to/noteplan-mcp"
    }
  }
}

重要提示：请将 /absolute/path/to/noteplan-mcp 替换为你克隆此仓库的实际路径。

步骤 3：重启 Claude Desktop

保存配置后，完全重启 Claude Desktop 以使更改生效。

可用工具

配置完成后，你可以在 Claude 对话中使用以下工具： | 工具 | 描述 | 参数 | |------|-------------|------------| | get_notes | 从 NotePlan 获取所有笔记 | 无 | | get_note_by_id | 通过 ID 获取特定笔记 | id（必需） | | search_notes | 通过查询搜索笔记 | query（必需） | | get_notes_by_folder | 从文件夹中获取笔记 | folder（必需） | | create_note | 创建新笔记 | title（必需）, content, folder | | create_daily_note | 创建每日笔记 | date（YYYY - MM - DD）, content | | update_note | 更新现有笔记 | id（必需）, title, content |

在 Claude 中的使用示例

设置完成后，你可以向 Claude 提出以下问题：

"Show me all my notes"（显示我所有的笔记）
"Search for notes containing 'project planning'"（搜索包含 'project planning' 的笔记）
"Create a new note titled 'Meeting Notes' in the 'Work' folder"（在 'Work' 文件夹中创建一个名为 'Meeting Notes' 的新笔记）
"Get today's daily note"（获取今天的每日笔记）
"Update note ID 'note123' with new content"（用新内容更新 ID 为 'note123' 的笔记）

Claude 将自动使用相应的 NotePlan MCP 工具来完成这些请求。

开发

开发模式

npm run dev

此命令将构建 TypeScript 代码，并使用 nodemon 在文件更改时自动重启服务器。

构建

npm run build

将 TypeScript 代码编译为 JavaScript 并输出到 build/ 目录。

测试

npm test

代码检查

npm run lint

项目结构

noteplan-mcp/
├── src/
│   ├── index.ts               # 主 MCP 服务器实现
│   ├── index.js               # HTTP 服务器（可选）
│   └── services/
│       └── noteService.ts     # 笔记管理逻辑
├── build/                     # 编译后的 JavaScript 输出
│   ├── index.js               # 编译后的 MCP 服务器
│   └── services/
│       └── noteService.js     # 编译后的笔记服务
├── tests/
│   └── index.test.js          # 测试文件
├── tsconfig.json              # TypeScript 配置
├── package.json
└── README.md

故障排除

Claude Desktop 无法连接

检查文件路径：确保 claude_desktop_config.json 中的路径是绝对路径且正确。
检查 Node.js：确保 Node.js 已安装并可从你的 PATH 访问。
检查日志：查看 Claude Desktop 的日志中的错误消息：
- macOS：~/Library/Logs/Claude/mcp-server-noteplan.log
- Windows：%LOCALAPPDATA%\Claude\Logs\mcp-server-noteplan.log

常见错误消息

"Cannot find module '/src/mcp-server.js'"：配置中的路径不正确，请使用绝对路径，而不是相对路径。
"Server disconnected"：检查 Node.js 是否已安装，并且可以使用 npm start 启动服务器。

测试你的设置

手动测试服务器：

cd /path/to/noteplan-mcp
npm run build
npm start

使用 MCP 检查器进行调试：
```
npm run inspector
```
检查 Claude Desktop 日志中的连接状态。
在 Claude 中尝试一个简单的命令："Can you show me my notes?"（你能显示我的笔记吗？）

配置

自定义 NotePlan 目录

默认情况下，服务器在标准位置查找 NotePlan 文件。如果你使用自定义目录，可以修改 noteService.js 文件以指向你的 NotePlan 数据目录。

环境变量

目前不需要环境变量，但未来版本可能支持：

NOTEPLAN_DATA_DIR：自定义 NotePlan 数据目录
MCP_LOG_LEVEL：日志详细程度

贡献

分叉仓库
创建功能分支：git checkout -b my-new-feature
进行更改并添加测试
运行测试套件：npm test
运行代码检查：npm run lint
提交更改：git commit -am 'Add some feature'
推送到分支：git push origin my-new-feature
提交拉取请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

若遇到 bug 或有功能请求，请在 GitHub 上开一个 issue。
有关 MCP 的一般问题，请查看 MCP 文档。
有关设置问题，请查看 Claude Desktop 文档。

noteplan-mcp