星战科技xingzhan.cloud
返回市场
笔记社区MCP

笔记社区MCP

作者：shimayuz17 星标更新：2025-11-24
安装使用来源：spider==github.com

项目介绍

技术文档摘要

note.com MCP Server

此MCP服务器通过note.com的API实现了从Claude Desktop、n8n及其他MCP客户端进行文章浏览、发布以及用户信息获取等功能。

📢 仓库迁移通知（2025年11月）

已迁移仓库。

  • ⚠️ 旧仓库: shimayuz/note-mcp-server （已删除）
  • ✅ 新仓库: shimayuz/note-com-mcp （当前仓库）

🔄 迁移内容

  • 📦 相同功能: 所有MCP工具和功能保持不变
  • 🚀 改进的安装: 更简单的安装步骤

📦 新的安装步骤

# 克隆新的仓库
git clone https://github.com/shimayuz/note-com-mcp.git
cd note-com-mcp

# 按照现有安装步骤进行安装
npm install
npm run build
npm run start:http

请勿使用旧仓库，请务必使用新仓库。

🚀 新功能: 支持HTTP/SSE传输（2025年11月）

支持流式HTTP传输！

  • 🌐 远程访问: 使用Cloudflare Tunnel从VPS上的n8n安全访问
  • 🔒 安全性: 认证信息保留在本地PC，可在远程使用
  • 🔄 自动化: 无缝集成到n8n等流程自动化工具中
  • 💰 免费: Cloudflare Tunnel是免费使用的

快速开始（n8n集成）

# 1. 启动HTTP服务器
npm run start:http

# 2. 启动Cloudflare Tunnel
cloudflared tunnel --url http://localhost:3000

# 3. 在n8n中连接
# HTTP Stream URL: 显示的Cloudflare URL + /mcp

详情请参阅 Cloudflare Tunnel 设置指南。

📚 目录

✨ 重构完成（2025年5月30日）

将2900行的单体文件拆分为16个模块，显著提高了维护性和性能。

  • 🚀 大小减少93%: 106KB → 7.5KB
  • 📁 模块化设计: 功能明确划分
  • ⚡ 加速: 提高了启动和运行速度
  • 🛠️ 开发效率: 维护、扩展和测试更加容易

功能

此MCP服务器提供了以下功能。

  • 文章搜索与浏览（支持按最新、热门、上升排序）
  • 包括用户和标签在内的note整体搜索
  • 用户搜索与个人资料查看
  • 文章详细分析（参与度分析、内容分析、价格分析等）
  • 获取自己的文章列表（包括草稿）
  • 发布和编辑文章（草稿）
  • 查看和发表评论
  • 管理点赞（获取、添加、删除）
  • 杂志搜索与浏览
  • 分类文章浏览
  • 获取PV统计信息
  • 获取并查看会员信息
  • 内容创意生成与竞争分析

认证信息

此服务器中，大多数读取功能（如文章搜索、用户信息等）无需认证即可使用。而以下功能需要note.com的认证信息：

  • 发布文章（草稿）
  • 发表评论
  • 添加或删除点赞
  • 获取PV统计信息
  • 获取会员信息

认证信息应在项目根目录创建的 .env 文件中设置。请使用 .env.example 文件作为模板，并填写您的信息。由于 .env 文件被 .gitignore 排除，因此可以安全地管理认证信息。

安装

所需条件

  • Node.js (v18及以上)
  • npm 或 yarn
  • Claude Desktop
  • note.com账户（如需使用发布功能）

安装步骤

  1. 克隆此仓库:

    git clone https://github.com/note-mcp-developer/note-mcp-server.git <您喜欢的目录名>
cd <您喜欢的目录名>

  2. 安装依赖包:

    npm install

  3. 创建环境配置文件: 将项目根目录中的 .env.example 文件复制为 .env 文件。

    cp .env.example .env

    打开创建的 .env 文件，设置您的note.com认证信息。 详情请参阅“认证信息设置方法”部分及 .env.example 文件内的注释。

    重要: .env 文件被 .gitignore 排除，因此不会误提交到仓库。请在本地安全保管。

  4. 构建并启动服务器:

    npm run build && npm run start

    此命令会编译TypeScript代码并启动服务器。

架构说明

此MCP服务器采用模块化设计以实现高维护性：

📁 目录结构

src/
├── config/          # 环境配置和API配置
├── types/           # TypeScript类型定义
├── utils/           # 公共工具
├── tools/           # 功能模块MCP工具
├── prompts/         # 提示模板
└── note-mcp-server-refactored.ts  # 主服务器

🚀 可用脚本

  • npm run start: 启动生产服务器（stdio）
  • npm run start:refactored: 启动重构版服务器（stdio）
  • npm run start:http: 启动HTTP传输版服务器
  • npm run dev:refactored: 开发模式（构建+启动，stdio）
  • npm run dev:http: 开发模式（构建+启动，HTTP）
  • npm run dev:watch: 文件监视模式
  • npm run dev:ts: 直接执行TypeScript（开发模式，stdio）
  • npm run dev:http:ts: 直接执行TypeScript（开发模式，HTTP）

⚡ 性能提升

  • 文件大小: 106KB → 7.5KB（减少93%）
  • 启动速度: 通过模块化加载加快
  • 维护性: 功能分离提高开发效率

认证信息设置方法

若要使用发布、点赞、获取会员信息等功能，需在项目根目录的 .env 文件中设置认证信息。请参考 .env.example 并按以下任一方式设置。

方法1：使用邮箱和密码认证（推荐）

在 .env 文件中设置您的note.com账户的邮箱地址、密码及用户ID：

重要: 若要使用草稿编辑功能，需从浏览器Cookie中获取 note_gql_auth_token 的值，并将其设置为 .env 文件中的 NOTE_GQL_AUTH_TOKEN。

NOTE_EMAIL=your_email@example.com
NOTE_PASSWORD=your_password
NOTE_USER_ID=your_note_user_id

此方法的优点是不像Cookie那样有到期问题。服务器启动时会自动认证。

方法2：基于Cookie的认证（替代方案，不推荐）

使用浏览器开发者工具等获取登录note.com时的Cookie信息，并设置到 .env 文件中。

NOTE_SESSION_V5=your_session_v5_cookie_value
NOTE_XSRF_TOKEN=your_xsrf_token_cookie_value
NOTE_USER_ID=your_note_user_id

注意: Cookie认证有有效期，可能需要定期更新。

与Claude Desktop的集成

  1. 安装并启动Claude Desktop

  2. 打开Claude Desktop的配置文件:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  3. 在配置文件中添加以下内容。请按以下任一方式设置。

    方法1：直接在配置文件中写入认证信息（推荐）

    {
  "mcpServers": {
    "note-api": {
      "command": "node",
      "args": [
        "/path/to/noteMCP/build/note-mcp-server-refactored.js"
      ],
      "env": {
        "NOTE_EMAIL": "note.com的邮箱地址",
        "NOTE_PASSWORD": "note.com的密码",
        "NOTE_USER_ID": "您的user ID"
      }
    }
  }
}

    若使用Cookie认证，则如下设置:

    {
  "mcpServers": {
    "note-api": {
      "command": "node",
      "args": [
        "/path/to/noteMCP/build/note-mcp-server-refactored.js"
      ],
      "env": {
        "NOTE_SESSION_V5": "您的session v5令牌",
        "NOTE_XSRF_TOKEN": "您的xsrf令牌",
        "NOTE_USER_ID": "您的user ID"
      }
    }
  }
}

    注意: /path/to/noteMCP 应替换为您实际克隆项目的绝对路径。

    方法2：使用.env文件（高级用户）

    此方法使用之前创建的 .env 文件。只需在配置文件中指定项目的路径。

    {
  "mcpServers": {
    "noteMCP": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/path/to/your/note-mcp-server", // 您克隆项目的根路径
      "mcp_version": "0.0.1"
    }
  }
}

    注意:

    • 此方法中，服务器会自动从项目根目录的 .env 文件中读取环境变量。
    • 此方法适合熟悉终端操作的用户。

  4. 重启Claude Desktop

与Cursor的集成

  1. 安装并启动Cursor

  2. 打开Cursor的MCP配置文件

    • macOS: ~/.cursor/mcp.json
    • Windows: %APPDATA%\.cursor\mcp.json 或打开Cursor设置，进入MCP设置页面，点击“添加全局MCP服务器”。

  3. 在配置文件中添加以下内容

    {
  "mcpServers": {
    "note-api": {
      "command": "node",
      "args": [
        "/path/to/noteMCP/build/note-mcp-server-refactored.js"
      ],
      "env": {
        "NOTE_EMAIL": "note.com的邮箱地址",
        "NOTE_PASSWORD": "note.com的密码",
        "NOTE_USER_ID": "您的user ID"
      }
    }
  }
}

    注意: /path/to/noteMCP 应替换为您实际克隆项目的绝对路径。

  4. 重启Cursor

与Windsurf的集成

  1. 安装并启动Windsurf

  2. 打开Windsurf的MCP配置文件

    • macOS: ~/.codeium/windsurf/mcp_config.json
    • Windows: %APPDATA%\.codeium\windsurf\mcp_config.json 或打开Windsurf设置，进入管理插件页面，点击“查看原始配置”。

  3. 在配置文件中添加以下内容

    {
  "mcpServers": {
    "note-api": {
      "command": "node",
      "args": [
        "/path/to/noteMCP/build/note-mcp-server-refactored.js"
      ],
      "env": {
        "NOTE_EMAIL": "note.com的邮箱地址",
        "NOTE_PASSWORD": "note.com的密码",
        "NOTE_USER_ID": "您的user ID"
      }
    }
  }
}

    注意: /path/to/noteMCP 应替换为您实际克隆项目的绝对路径。

  4. 重启Windsurf

远程MCP连接（HTTP/SSE传输）

通过使用流式HTTP传输，可以从Cursor、ChatGPT、OpenAI Responses API等远程连接MCP服务器。

推荐配置: 使用Cloudflare Tunnel的安全连接

如果您在VPS上自托管n8n，可以通过使用Cloudflare Tunnel，在保持认证信息存储在本地PC的同时，安全地进行远程访问。

详细步骤请参阅 Cloudflare Tunnel 设置指南。

启动HTTP服务器

# 构建并启动
npm run build && npm run start:http

# 或者在开发模式下启动
npm run dev:http

默认情况下会在 http://127.0.0.1:3000 启动。若要更改端口或主机，请在 .env 文件中添加以下内容：

MCP_HTTP_PORT=3000
MCP_HTTP_HOST=127.0.0.1

可用端点

  • 健康检查: http://127.0.0.1:3000/health
  • MCP端点: http://127.0.0.1:3000/mcp
  • SSE端点: http://127.0.0.1:3000/sse

在n8n中设置连接

在n8n中使用“MCP Client HTTP Streamable”节点进行连接：

# 获取用于n8n连接的URL
./scripts/manage-services.sh test

n8n设置:

HTTP Stream URL: https://note-mcp.composition2940.com/mcp
HTTP Connection Timeout: 60000
Messages Post Endpoint: (留空)
Additional Headers: (留空)

支持的功能:

  • ✅ tools/list - 获取23个工具列表
  • ✅ tools/call - 执行search-notes, get-note工具
  • ✅ 支持JSON-RPC POST请求
  • ✅ 支持note.com认证信息的传递

可用工具（支持HTTP）:

  • search-notes: note.com文章搜索
  • get-note: 获取文章详情
  • 其他21个工具（仅列出，推荐使用stdio）

在Cursor中设置远程连接

在Cursor的配置文件（~/.cursor/mcp.json）中添加以下内容：

{
  "mcpServers": {
    "note-api-remote": {
      "url": "http://127.0.0.1:3000/mcp",
      "transport": "sse"
    }
  }
}

在ChatGPT / OpenAI Responses API中连接

使用OpenAI API时，可以这样指定MCP服务器的URL：

from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "note中的人气文章"}],
    mcp_servers=[{
        "url": "http://127.0.0.1:3000/mcp",
        "transport": "sse"
    }]
)

安全注意事项

  • 默认情况下仅允许从 127.0.0.1（localhost）访问
  • 如需允许外部访问，请实施适当的防火墙设置和认证机制
  • 强烈建议在生产环境中使用HTTPS

🚀 自动启动设置（macOS）

在macOS上，您可以设置 note-mcp-server 和 Cloudflare Tunnel 在电脑启动时自动启动。

自动启动设置

# 1. 设置服务管理脚本为可执行
chmod +x scripts/manage-services.sh

# 2. 设置自动启动（macOS LaunchAgent）
./scripts/manage-services.sh setup

# 3. 启动服务
./scripts/manage-services.sh start

# 4. 查看状态
./scripts/manage-services.sh status

服务管理命令

# 查看状态
./scripts/manage-services.sh status

# 启动服务
./scripts/manage-services.sh start

# 停止服务
./scripts/manage-services.sh stop

# 重启服务
./scripts/manage-services.sh restart

# 查看日志
./scripts/manage-services.sh logs

# 健康检查
./scripts/manage-services.sh health

# 显示n8n连接用URL
./scripts/manage-services.sh test

自动启动原理

  • LaunchAgent: macOS标准功能，电脑启动时自动执行
  • note-mcp-server: ~/Library/LaunchAgents/com.note-mcp-server.plist
  • Cloudflare Tunnel: ~/Library/LaunchAgents/com.cloudflared.note-mcp.plist
  • 日志管理: 日志保存在 ~/noteMCP/logs/ 目录

手动启动/停止

# 控制单独的服务
launchctl start com.note-mcp-server
launchctl stop com.note-mcp-server
launchctl start com.cloudflared.note-mcp
launchctl stop com.cloudflared.note-mcp

使用方法

您可以在Claude Desktop中尝试以下查询。

搜索与浏览（无需认证）

  • “在note中搜索关于‘编程’的热门文章”
  • “在note中按最新顺序搜索‘编程’的文章”
  • “分析用户‘username’的文章，告诉我受欢迎的原因”
  • “在note中搜索所有与‘编程’相关的用户和标签”
  • “详细分析关于‘编程’的文章，告诉我参与度的趋势”

需要认证才能使用的功能

  • “获取我的note中草稿文章列表”
  • “我想打开编辑ID为n12345的草稿文章页面”
  • “创建标题为‘测试文章’，内容为‘这是测试’的草稿文章”
  • “告诉我我的note账户最新文章的PV数量