使用说明

MCP服务器概念

模型上下文协议（MCP）服务器，通过Notion API提供对Notion工作空间的全面读写访问。

特性

🔍 搜索和检索 页面、数据库和块
📝 创建和更新 内容丰富的页面
🗃️ 数据库操作 -查询、创建和更新数据库条目
🏗️ 阻止操纵 -追加、更新和删除块
🔒 安全认证 使用Notion集成令牌
🛡️ 错误处理 具有适当的MCP错误响应
📊 综合录井 用于调试和监控

快速开始

1.安装

git clone https://github.com/your-username/notion-mcp-server.git
cd notion-mcp-server
npm install

2.概念集成设置

首选概念开发者
点击“新建集成”
填写基本信息：
- 名称：“MCP服务器集成”
- 关联工作区：选择您的工作区
- 功能：读取内容、更新内容、插入内容
点击“提交”
复制“内部集成令牌”

3.配置

创建一个 .env 项目根目录中的文件：

NOTION_TOKEN=your_notion_integration_token_here

备注：服务器自动查找并加载 .env 无论MCP客户端从何处运行该文件，都可以从项目目录中删除该文件。

4.授予页面访问权限

对于您要访问的每个Notion页面/数据库：

在Notion中打开页面
点击“…”菜单→ “添加连接”
选择您的集成

5.运行服务器

# Development
npm run dev

# Production
npm start

客户端集成

克劳德代码（CLI）

将服务器添加到您的Claude Code MCP配置中：

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

或者使用npm：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-p", "/path/to/notion-mcp-server", "node", "dist/index.js"]
    }
  }
}

服务器将自动读取 NOTION_TOKEN 从你的 .env 文件。

克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

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

服务器将自动读取 NOTION_TOKEN 从你的 .env 项目目录中的文件。

ChatGPT（通过OpenAI）

对于ChatGPT集成，您需要使用JSON-RPC传输运行服务器。创建包装脚本：

notion-mcp-wrapper.js:

#!/usr/bin/env node
const { spawn } = require('child_process');

const server = spawn('node', ['/path/to/notion-mcp-server/dist/index.js'], {
  env: process.env, // Inherits environment variables including NOTION_TOKEN from .env
  stdio: ['pipe', 'pipe', 'pipe'],
  cwd: '/path/to/notion-mcp-server' // Ensures .env file is found
});

process.stdin.pipe(server.stdin);
server.stdout.pipe(process.stdout);
server.stderr.pipe(process.stderr);

server.on('exit', (code) => {
  process.exit(code);
});

然后配置ChatGPT以使用：

{
  "tools": [
    {
      "type": "mcp_server",
      "mcp_server": {
        "command": "node",
        "args": ["/path/to/notion-mcp-wrapper.js"]
      }
    }
  ]
}

替代方案：全球安装

为了更容易配置，您可以全局安装服务器：

# Make the server globally available
npm link

# Or install globally if published
npm install -g notion-mcp-server

然后在配置中使用：

{
  "mcpServers": {
    "notion": {
      "command": "notion-mcp-server"
    }
  }
}

备注：使用全局安装时，请确保 .env 文件位于客户端运行的工作目录中，或设置 NOTION_TOKEN 作为系统环境变量。

安全最佳实践

✅ 做：将您的Notion令牌保存在 .env 文件

NOTION_TOKEN=secret_your_notion_integration_token_here

❌ do not 的常用口语形式：将令牌直接放入MCP客户端配置中

// AVOID THIS - tokens exposed in config files
{
  "mcpServers": {
    "notion": {
      "env": {
        "NOTION_TOKEN": "secret_token_here"
      }
    }
  }
}

系统环境变量（可选）

如果您更喜欢系统范围的环境变量而不是 .env 文件夹：

# Add to your shell profile (.bashrc, .zshrc, etc.)
export NOTION_TOKEN="your_notion_integration_token_here"

这种方法适用于全球安装和容器化部署。

MCP工具可用

页面操作

`notion_search_pages`

在工作区中搜索页面。

{
  "query": "meeting notes",
  "filter": "page",
  "sort": "last_edited_time"
}

`notion_get_page`

检索特定页面及其所有内容。

{
  "page_id": "page-uuid-here"
}

`notion_create_page`

创建一个包含内容的新页面。

{
  "parent": {
    "type": "page_id",
    "page_id": "parent-page-uuid"
  },
  "title": "New Page Title",
  "content": "# Heading\n\nThis is some content."
}

`notion_update_page`

更新现有页面的属性和内容。

{
  "page_id": "page-uuid-here",
  "title": "Updated Title",
  "content": "Updated content here"
}

`notion_append_blocks`

将块附加到现有页面。

{
  "block_id": "page-or-block-uuid",
  "content": "Additional content to append"
}

数据库操作

`notion_query_database`

使用过滤器和排序查询数据库。

{
  "database_id": "database-uuid-here",
  "filter": {
    "property": "Status",
    "select": {
      "equals": "In Progress"
    }
  },
  "sorts": [
    {
      "property": "Created",
      "direction": "descending"
    }
  ]
}

`notion_create_database_page`

在数据库中创建新页面。

{
  "database_id": "database-uuid-here",
  "properties": {
    "Name": {
      "title": [
        {
          "text": {
            "content": "New Task"
          }
        }
      ]
    },
    "Status": {
      "select": {
        "name": "To Do"
      }
    }
  },
  "content": "Task description here"
}

`notion_update_database_page`

更新数据库页面的属性。

{
  "page_id": "page-uuid-here",
  "properties": {
    "Status": {
      "select": {
        "name": "Completed"
      }
    }
  }
}

区块操作

`notion_get_blocks`

获取页面或块的子块。

{
  "block_id": "block-uuid-here"
}

`notion_update_block`

更新特定块的内容。

{
  "block_id": "block-uuid-here",
  "content": "Updated block content"
}

`notion_delete_block`

删除特定块。

{
  "block_id": "block-uuid-here"
}

公用事业运营

`notion_get_users`

列出工作区中的所有用户。

`notion_get_databases`

列出可访问的数据库。

配置

环境变量

变量	描述	必填
`NOTION_TOKEN`	Notion集成令牌	是
`LOG_LEVEL`	日志记录级别（调试、信息、警告、错误）	否（默认值：信息）
`PORT`	用于健康检查的服务器端口	否（默认值：3000）

集成能力

创建Notion集成时，请确保启用：

✅ 阅读内容 -所有读取操作都需要
✅ 更新内容 -更新页面/块所需
✅ 插入内容 -创建页面/块所需
✅ 读取用户信息 -用户操作所需

错误处理

服务器实现了全面的错误处理：

身份验证错误 -Notion令牌无效或缺失
权限错误 -拒绝访问特定页面/数据库
速率限制 -指数回退自动重试
验证错误 -无效参数或格式错误的请求
网络错误 -连接超时和重试

发展

项目结构

notion-mcp-server/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── tools/                # MCP tool implementations
│   │   ├── pages.ts          # Page-related tools
│   │   ├── databases.ts      # Database-related tools
│   │   ├── blocks.ts         # Block-related tools
│   │   └── utils.ts          # Utility tools
│   ├── notion/               # Notion API wrappers
│   │   ├── client.ts         # Notion client setup
│   │   ├── converters.ts     # Content converters
│   │   └── validators.ts     # Input validation
│   └── utils/
│       ├── logger.ts         # Logging utilities
│       └── errors.ts         # Error handling
├── tests/                    # Test files
├── docs/                     # Additional documentation
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

建筑

npm run build

测试

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run integration tests (requires valid Notion token)
npm run test:integration

代码检查

npm run lint
npm run lint:fix

贡献

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
提交您的更改： git commit -m 'Add amazing feature'
推到分支： git push origin feature/amazing-feature
打开拉取请求

开发指南

遵循TypeScript的最佳实践
为新功能添加测试
更新API变更文档
使用常规提交消息
在提交PR之前，确保所有测试都通过

安全

永不承诺 .env 文件或令牌到存储库
使用环境变量进行敏感配置
定期轮换您的Notion集成令牌
授予访问权限时遵循最小权限原则

故障排除

常见问题

“无法在模块外使用import语句”错误

本项目使用ES模块。确保你的 package.json 包括：

{
  "type": "module"
}

JSON中数组元素后应有“”、“”或“]”错误

当日志被发送到stdout而不是stderr时，会发生此错误，从而干扰MCP JSON通信。服务器已修复为将所有日志发送到stderr，但如果您遇到以下情况：

确保您使用的是最新版本
检查是否 console.log 语句在代码中
更新服务器后重新启动Claude Desktop

“缺少必需的环境变量：NOTION_TOKEN”错误

服务器自动加载 .env 项目目录中的文件。如果您看到此错误：

确保 .env 文件与您的令牌一起存在于项目根目录中：
```
NOTION_TOKEN=your_notion_integration_token_here
```
验证令牌是否有效且未过期
检查令牌周围是否没有多余的空格或引号

“找不到模块”错误

验证MCP客户端配置中的路径指向正确的位置
确保您已经构建了项目： npm run build
检查一下 dist/ 文件夹存在并包含 index.js

“未经授权”错误

验证您的 NOTION_TOKEN 在以下方面是正确的 .env 文件
确保已将集成添加到您正在访问的页面/数据库中
检查您的集成是否具有所需的功能

“找不到对象”错误

验证页面/数据库ID是否正确
确保集成可以访问特定对象
检查对象是否已被删除或移动

速率限制

服务器通过指数回退自动处理速率限制
如果遇到持续的速率限制，请考虑降低请求频率

调试模式

启用调试日志记录：

LOG_LEVEL=debug npm start

这将输出有关API调用和响应的详细信息。

测试服务器

要验证服务器是否正常工作，请执行以下操作：

# Build the project
npm run build

# Test TypeScript compilation
npm run typecheck

# Run the server (will start and wait for MCP connections)
npm start

更新日志

看更改日志.md 查看详细的更改列表。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

致谢

API通知提供卓越的API
模型上下文协议对于MCP规范
开源社区的灵感和贡献

支持

由以下材料制成❤️ 开源社区