Custom Notion MCP Server

自定义概念MCP服务器（TypeScript）

模型上下文协议（MCP）服务器的TypeScript实现，将Notion工作区连接到Claude Desktop，使Claude能够使用缓存、过滤和错误处理等高级功能搜索、读取和查询您的Notion内容。

特性

核心功能

• 搜索页面：按关键字搜索所有可访问的Notion页面
• 获取页面内容：检索支持10多种块类型的完整页面内容
• 列出数据库：发现工作区中的所有数据库
• 查询数据库：获取包含所有属性值的完整数据库条目
• 获取缓存统计信息：监视缓存性能和统计信息

智能功能

• 自动筛选已停用页面：自动排除具有可配置关键字的页面
• 配置文件：通过以下方式自定义过滤和缓存行为 config.json
• 缓存：具有可配置TTL的内存内缓存，以减少API调用
• 错误处理：针对速率限制和连接问题，采用指数回退自动重试
• 块支持：提取标题、列表、代码块、引号、待办事项、子页等

快速开始

先决条件

• Node.js 24.11.0（通过Volta管理）
• 具有管理员权限的Notion帐户
• Claude桌面应用程序

安装

1. 克隆或下载此存储库
2. 安装依赖项：

npm install

1. 构建项目：

npm run build

1. 运行测试（可选）：

npm test

设置概念集成

1. 首选 概念整合
2. 点击“+新集成”
3. 为其命名（例如，“Claude MCP Integration”）
4. 将功能设置为“读取内容”（最低要求）
5. 复制“内部集成令牌”（以开头 secret_)

通过集成共享内容

重要：默认情况下，集成将无法访问任何内容。您可以通过两种方式共享页面/数据库：

在集成设置中配置

1. 打开您刚刚创建的新概念集成
2. 单击菜单上的“访问”
3. 单击编辑访问权限
4. 选择要共享的页面/数据库，然后单击保存

或在Notion工作区中配置

1. 在Notion中打开页面或数据库
2. 点击右上角的“…”菜单
3. 选择“连接”
4. 查找并添加您的集成
5. 对您希望Claude访问的每个页面/数据库重复此操作。

配置Claude桌面

1. 找到您的Claude Desktop配置文件：

- 视窗: %APPDATA%\Claude\claude_desktop_config.json - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json

1. 添加MCP服务器配置：

{
  "mcpServers": {
    "custom-notion-mcp": {
      "command": "node",
      "args": ["C:\\your\\path\\to\\your\\serevr\\build\\index.js"],
      "env": {
        "NOTION_TOKEN": "secret_your_token_here"
      }
    }
  }
}

将路径替换为您的实际绝对路径 build/index.js.

1. 重新启动克劳德桌面

配置

通过编辑自定义服务器行为 src/config.json:

{
  "filtering": {
    "excludeKeywords": ["deprecated", "depricated", "archive"],
    "excludePageIds": [],
    "excludeDatabaseIds": [],
    "includeOnlyPageIds": [],
    "includeOnlyDatabaseIds": []
  },
  "caching": {
    "enabled": true,
    "ttlMinutes": 5
  }
}

配置选项

• excludeKeywords：从搜索/列表结果中筛选出的关键字数组（不区分大小写）
• excludePageId：要排除的特定页面ID
• 排除数据库ID：要排除的特定数据库ID
• 仅包含PageId：如果指定，则只包括这些页面ID（白名单）
• 仅包括数据库ID：如果指定，则只包括这些数据库ID（白名单）
• caching.enabled：打开/关闭缓存
• caching.ttl分钟：缓存生存时间（分钟）（默认值：5）

用法

配置后，Claude将可以访问五个工具：

1.搜索理念

按关键字搜索页面：

"Search my Notion for pages about project planning"

根据配置关键字自动筛选页面。

2.获取页面

获取特定页面的完整内容：

"Fetch the content of this Notion page: [page-id or URL]"

支持提取：

• 标题（H1、H2、H3）
• 段落
• 列表（项目符号、编号）
• 代码块
• 语录
• 待办事项
• 切换块
• 子页面和数据库

3.列出数据库

查看所有可用数据库：

"List all databases in my Notion workspace"

通过检查页父关系智能地发现数据库。

4.查询数据库

从数据库中获取所有条目：

"Show me all entries in database [database-id]"

5.获取缓存统计信息

监控缓存性能：

"Get cache stats"

显示缓存状态、缓存项数和TTL设置。

建筑

技术栈

• @模型上下文协议/sdk：用于服务器实现的官方MCP SDK
• @通知/客户：官方通知API客户
• 黄道：工具参数的运行时类型验证
• 维测试：具有覆盖支持的测试框架
• TypeScript：类型安全开发

项目结构

custom-notion-mcp-ts/
├── src/
│   ├── server/
│   │   ├── tools/              # Individual tool implementations
│   │   │   ├── searchNotion.ts
│   │   │   ├── fetchPage.ts
│   │   │   ├── queryDatabase.ts
│   │   │   ├── listDatabases.ts
│   │   │   └── getCacheStats.ts
│   │   ├── index.ts            # Server setup and tool registration
│   │   └── config.ts           # Configuration loader
│   ├── utils/
│   │   ├── cache.ts            # Caching implementation
│   │   ├── withRetry.ts        # Error handling and retry logic
│   │   ├── filter.ts           # Filtering utilities
│   │   ├── extractors.ts       # Data extraction helpers
│   │   └── logger.ts           # Logging utilities
│   ├── domain.ts               # Type definitions
│   ├── config.json             # Configuration file
│   └── index.ts                # Entry point
├── test/
│   ├── cache.test.ts           # Cache unit tests
│   └── withRetry.test.ts       # Retry logic tests
├── build/                      # Compiled JavaScript output
├── package.json                # Dependencies and scripts
├── tsconfig.json               # TypeScript configuration
└── README.md                   # This file

支持的块类型

页数（fetch_page）

• 段落
• 标题1、2、3
• 项目符号列表项
• 编号列表项
• 代码块（带语言语法）
• 语录
• 切换块
• 待办事项（状态已勾选）
• 分隔线
• 子页面（带URL）
• 子数据库（带URL）

数据库（query_database）

• 标题
• 富文本
• 数字
• 选择/多选
• 日期
• 复选框
• 统一资源定位符
• 电子邮件
• 电话号码
• 状态

其他物业类型将显示为 [type] 在输出中。

智能功能详解

1.自动过滤

页面和数据库会根据以下内容自动筛选：

• 关键字排除：跳过标题中带有“弃用”、“存档”等的项目
• ID排除：排除特定页面/数据库ID
• ID包含：仅将特定ID列入白名单

2.缓存层

• 具有可配置TTL的内存缓存
• 缓存 fetch_page 和 query_database 结果
• 将缓存命中/未命中记录到stderr
• 减少API调用并缩短响应时间
• 可以通过配置禁用

3.错误处理

• 自动重试速率限制错误（HTTP 429）
• 尊重 Retry-After 来自Notion API的标头
• 连接错误的指数回退
• 最多3次重试尝试
• 详细的错误记录

4.性能监控

使用 get_cache_stats 监控：

• 缓存命中率
• 缓存项目数
• TTL配置
• 缓存状态（启用/禁用）

发展

构建

npm run build

从编译TypeScript src/ 到 build/ 目录。

测试

npm test           # Run tests
npm run test       # Run tests with coverage

测试由Vitest编写，包括：

• 缓存功能测试
• 重试逻辑测试
• 工具特定测试（如果添加）

开发工作流程

1. 在中更改源文件 src/
2. 运行测试： npm test
3. 构建： npm run build
4. 重新启动Claude Desktop以重新加载服务器

调试

服务器记录到stderr。您将看到：

缓存命中:

[CACHE HIT] Page abc123 served from cache

缓存未命中:

[CACHE MISS] Fetching page abc123 from Notion API

速率限制:

Rate limited. Waiting 2000ms before retry 1/3

要查看日志，请从终端运行Claude Desktop或检查日志文件。

测试缓存

1. 检查初始统计数据： "Get cache stats"
2. 获取页面： "Fetch page [id]" （缓慢-API调用）
3. 查看统计数据： "Get cache stats" （应显示1个缓存项）
4. 获取相同页面： "Fetch page [id]" （快速-从缓存中）
5. 等待5分钟（或配置TTL）
6. 重新获取： "Fetch page [id]" （速度慢-缓存已过期）

故障排除

搜索时“未找到结果”

原因：页面未与集成共享

解决方案：在Notion中打开页面→ “…”菜单→ “连接”→ 添加您的集成

“未找到数据库”

原因：数据库未与集成共享

解决方案：共享至少一个作为数据库子级的页面，或直接共享数据库

缓存不工作

原因：配置中禁用缓存

解决方案：检查 src/config.json 并确保 caching.enabled: true

参数不被接受

原因：旧版本或工具注册不正确

解决方案:

1. 重建： npm run build
2. 重新启动克劳德桌面
3. 验证Claude配置中的路径是否正确

服务器无法启动

可能的原因:

• NOTION_TOKEN 未在Claude Desktop配置中设置
• 令牌格式无效（必须以开头 secret_)
• 错误的Node.js版本（需要24.11.0）
• 缺少构建目录(npm run build)

性能提示

1. 启用缓存：大大减少了对频繁访问内容的API调用
2. 调整TTL：对于频繁变化的内容，TTL较低，对于静态内容，TTL较高
3. 使用筛选：排除不相关的页面以减小搜索结果大小
4. 监控缓存统计数据：定期检查缓存性能

资源

• MCP文件
• API文件通知
• Notion MCP服务器（官方）
• 创建概念集成

许可证

ISC

安全说明

切勿将Notion集成令牌提交到版本控制。

始终使用环境变量或配置文件（通过排除 .gitignore)以存储敏感凭据。