AI导哈

Notion集成服务器

连接Notion工作区与Claude Code的服务器，实现Notion页面的搜索、读写和数据库查询功能。

  • by tonutoz
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 tonutoz/notion-mcp-server

使用说明

MCP服务器概念

用于克劳德代码集成的概念MCP（模型上下文协议）服务器。

概述

此服务器将您的Notion工作区连接到Claude Code，使Claude能够直接搜索、读取和写入Notion页面。

特性

  • 🔍 搜索Notion页面和数据库
  • 📖 读取页面内容和数据库条目
  • ✍️ 创建和更新页面
  • 🔎 使用过滤器和排序查询数据库
  • 🔐 安全的API密钥管理
  • 🚀 API全面集成

快速开始

对于大多数用户，使用stdio模式（更简单、更稳定）:

# 1. Install
npm install && npm run build

# 2. Get Notion API key from https://www.notion.so/my-integrations

# 3. Register with Claude Code
claude mcp add --transport stdio notion \
  --env NOTION_API_KEY=your_key_here \
  -- node /absolute/path/to/dist/index.js

# 4. Use in Claude Code
claude
> /mcp
> 내 Notion 페이지를 검색해줘

📘 详细指南： docs/STDIO_MODE.md

建筑

运输方式

此服务器支持三种传输模式：

  1. 标准输入/输出 - ⭐ 建议个人使用

  2. HTTP（流式HTTP） - ⭐ 建议用于团队/VM部署

    • 现代MCP协议（2025-03-26）
    • 中央服务器部署
    • 支持多用户身份验证
    • 📘 HTTP部署指南

MCP能力

  1. 工具：与Notion API交互的函数
  2. 资源：访问Notion页面和数据库
  3. 认证：用户API密钥管理

先决条件

  • Node.js 18+或Node.js 20+
  • 具有API访问权限的Notion帐户
  • 在Notion工作区中创建Notion集成

安装

选项1：本地安装

# Clone the repository
git clone <repository-url>
cd notion-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

选项2:VM/服务器部署（stdio模式）

对于在多个用户将通过SSH连接的VM上部署：

# On your VM
git clone <repository-url>
cd notion-mcp-server
npm install
npm run build

# Start the server (stdio mode)
npm start

选项3:HTTP服务器部署（建议用于VM）

对于具有Streamable HTTP的真正中央服务器：

# On your VM
git clone <repository-url>
cd notion-mcp-server
npm install
npm run build

# Start HTTP server
npm run start:http

# Or with PM2 for production
npm install -g pm2
pm2 start dist/index-http.js --name notion-mcp-http
pm2 save

📘 看 docs/HTTP_MODE.md 获取完整的HTTP设置指南

获取您的通知API密钥

  1. 首选https://www.notion.so/my-integrations
  2. 点击“+新集成”
  3. 给它起个名字（例如，“克劳德代码集成”）
  4. 选择要连接的工作区
  5. 点击“提交”
  6. 复制“内部集成令牌”-这是您的API密钥
  7. 重要：与您要访问的页面/数据库共享集成：
    • 在Notion中打开页面
    • 点击“…”菜单→ “添加连接”
    • 选择您的集成

Claude代码配置

stdio模式（推荐）

使用此服务器的最简单、最可靠的方法：

claude mcp add --transport stdio notion \
  --env NOTION_API_KEY=secret_your_notion_key \
  --env USER_ID=optional_user_id \
  -- node /absolute/path/to/notion-mcp-server/dist/index.js

Windows示例:

claude mcp add --transport stdio notion \
  --env NOTION_API_KEY=ntn_xxxxxxxxxx \
  -- node C:/IdeaProject/mcp/notion-mcp-server/dist/index.js

Mac/Linux示例:

claude mcp add --transport stdio notion \
  --env NOTION_API_KEY=ntn_xxxxxxxxxx \
  -- node /Users/username/notion-mcp-server/dist/index.js

验证:

claude mcp list
# Should show: notion: node ... - ✓ Connected

📘 完整的stdio指南： docs/STDIO_MODE.md

Claude桌面应用程序配置

对于Claude Desktop（非CLI），编辑配置文件：

Mac/Linux: ~/.claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/absolute/path/to/notion-mcp-server/dist/index.js"],
      "env": {
        "NOTION_API_KEY": "secret_your_notion_key"
      }
    }
  }
}

高级：HTTP模式（团队部署）

对于团队或远程部署，请参阅 docs/HTTP_MODE.md

首先，在HTTP服务器上注册：

curl -X POST http://your-server:3000/register \
  -H "Content-Type: application/json" \
  -d '{"notionApiKey": "secret_xxx"}'

然后连接克劳德代码：

claude mcp add --transport http notion \
  --header "X-User-Id: YOUR_USER_ID" \
  --header "X-Api-Key: YOUR_NOTION_KEY" \
  http://your-server:3000/mcp

备注：对于生产，请使用带有适当SSL证书的HTTPS。

方法3:NPM包（即将推出）

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "your-notion-api-key",
        "USER_ID": "your-user-id"
      }
    }
  }
}

可用工具

配置后，Claude Code可以使用这些工具：

1. search_pages

在您的工作区中搜索Notion页面。

{
  query: "project notes",
  page_size: 10
}

2. search_databases

查找Notion数据库。

{
  query: "tasks",
  page_size: 10
}

3. get_page

获取特定页面的详细信息。

{
  page_id: "page-id-here"
}

4. get_page_content

阅读页面的内容块。

{
  page_id: "page-id-here"
}

5. create_page

创建新页面。

{
  parent: { page_id: "parent-page-id" },
  title: "New Page",
  content: [
    {
      object: "block",
      type: "paragraph",
      paragraph: {
        rich_text: [{ type: "text", text: { content: "Hello!" } }]
      }
    }
  ]
}

6. append_blocks

向现有页面添加内容。

{
  page_id: "page-id-here",
  blocks: [/* block objects */]
}

7. query_database

使用筛选器查询数据库。

{
  database_id: "database-id-here",
  filter: {
    property: "Status",
    select: { equals: "In Progress" }
  }
}

8. get_database

获取数据库架构和属性。

{
  database_id: "database-id-here"
}

安全考虑

  • API密钥在存储前使用SHA-256进行散列
  • 每个用户都有一个唯一的身份验证ID
  • 响应中从不记录或公开密钥
  • 商店 users.json 安全并定期备份
  • 对敏感数据使用环境变量
  • 考虑使用HTTPS进行远程部署

发展

# Run in development mode with auto-reload
npm run dev

# Build
npm run build

# Production
npm start

故障排除

“Notion API密钥无效”

  • 验证您的API密钥是否正确
  • 检查集成是否与您的页面共享
  • 确保集成具有必要的权限

“找不到用户”

  • 确保您已运行注册脚本
  • 验证用户ID是否与注册时的ID匹配

Claude Code无法连接

  • 检查index.js的路径是否为绝对路径
  • 验证Node.js是否在您的PATH中
  • 检查克劳德代码日志是否有错误

SSH连接问题（VM部署）

  • 确保配置了SSH密钥身份验证
  • 首先手动测试SSH连接
  • 检查VM上的防火墙规则

VM部署最佳实践

对于生产VM部署：

  1. 使用流程管理器 （PM2，系统d）：
npm install -g pm2
pm2 start dist/index.js --name notion-mcp-server
pm2 save

  1. 设置自动备份 的 users.json

  2. 配置防火墙 限制访问

  3. 使用SSH密钥身份验证 仅限（禁用密码验证）

  4. 监控日志:

pm2 logs notion-mcp-server
  1. 保持服务器更新:
git pull
npm install
npm run build
pm2 restart notion-mcp-server

API 参考

有关Notion API的详细文档，请参阅： https://developers.notion.com/reference/intro

许可证

麻省理工学院

贡献

欢迎投稿！请打开问题或提交拉取请求。

支持

对于问题和疑问：

  • 检查故障排除部分
  • 审查API文件通知
  • 打开GitHub问题

相关 MCP