mcp-notion-usage-guide

MCP Notion工具使用指南

Problem

MCP Notion工具的使用方式和错误处理在官方文档中没有详细说明，遇到错误时难以快速定位和解决，尤其是在访问数据库视图和查询数据时容易遇到问题。

Context / Trigger Conditions

• 调用mcp__notion__notion-fetch工具访问view URL时返回错误："URL type view not currently supported for fetch tool"
• 需要获取Notion数据库的字段结构和schema信息
• 需要查询数据库中的所有条目或过滤特定条目
• 开发自动化工作流需要从Notion数据库获取数据

Solution

1. 数据库访问最佳实践

当需要访问Notion数据库内容时：

1. 优先使用数据库页面URL，而不是view URL，避免不支持的URL类型错误
2. 数据库页面URL格式通常为：https://www.notion.so/[workspace]/[database-id]
3. 调用mcp__notion__notion-fetch工具时传入数据库页面URL，即可获取完整的数据库schema信息，包括所有字段定义、选项配置等

2. 获取数据库条目内容

要获取数据库中的所有条目：

1. 首先通过数据库页面URL获取对应的data source URL，格式为：collection://[data-source-id]
2. 使用该data source URL作为mcp__notion__notion-fetch的参数，并搭配SQL查询语句获取内容
3. 示例查询：

   # 获取所有条目的基本信息
   query = """
   SELECT "Name", "Institution", "Category", "Advisor", "userDefined:URL", "url" 
   FROM "collection://[data-source-id]"
   """
   

3. 常见错误解决方案

错误："URL type view not currently supported for fetch tool"

• 原因：当前MCP Notion工具不支持直接访问view类型的URL
• 解决方案：改用数据库的主页面URL访问，所有view的数据都可以通过SQL查询在主数据源上实现
• 替代方案：如果需要特定view的过滤条件，可以在SQL查询中添加对应的WHERE子句实现相同效果

限制：SQL查询仅返回表结构，无实际数据

• 现象：使用SELECT查询数据库内容时，仅返回表结构和schema信息，没有实际数据记录
• 原因：当前版本MCP Notion工具的SQL查询功能尚未完全实现，只支持获取表结构，不支持查询实际数据
• 解决方案：
  1. 如果需要获取数据库中的实际记录，使用mcp__notion__notion-search工具搜索特定条目，然后通过mcp__notion__notion-fetch获取单个页面的完整属性
  2. 直接访问数据库页面或通过Notion API获取完整数据集
• 注意：技能文档中的SQL查询示例仅为预期功能，目前暂不支持使用

4. 数据库Schema更新（添加MULTI_SELECT新选项）

当需要在数据库中创建新页面，但目标字段的MULTI_SELECT选项中不存在需要的值时：

1. 先使用notion-update-data-source更新schema，添加新选项
2. 然后才能创建包含该选项值的页面

示例：

ALTER COLUMN "Institution" SET MULTI_SELECT('existing1':blue, 'existing2':red, 'NewSchool':green)

注意事项：

• 必须列出所有现有选项和新选项，否则会丢失已有选项
• 颜色值可选：default, gray, brown, orange, yellow, green, blue, purple, pink, red
• 更新完成后，SQLite表定义中的枚举值列表会自动更新

5. 创建页面时的属性命名注意事项

• URL属性必须使用userDefined:URL（URL是保留字，不能直接写为"URL"）
• 日期字段需要拆分为date:[field-name]:start、date:[field-name]:end和date:[field-name]:is_datetime
• 多选字段的内容需要以JSON数组格式传递，如["THU", "Yale"]
• MULTI_SELECT字段的值必须是数据库schema中已定义的选项，否则创建会失败