项目简介

本项目是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在帮助用户通过 LLM 客户端管理 Notion 内容数据库。它作为一个工作坊项目，引导用户逐步搭建一个能够与 Notion API 交互的 MCP 服务器，实现内容的查询、创建和更新等功能。

主要功能点

工具 (Tools) 注册和执行: 通过 '@mcp.tool()' 装饰器注册了 'find_posts', 'create_post', 'add_content_to_post' 等工具，允许 LLM 客户端调用这些工具来操作 Notion 数据库。
资源 (Resources) 管理 (隐式): 虽然没有显式资源管理，但 Notion 数据库本身可以被视为一个外部资源，服务器通过 Notion API 进行访问和管理。
Prompt 模板 (Prompts) (未实现): 仓库中没有 Prompt 模板的实现，但框架支持 Prompt 模板的定义和渲染。
JSON-RPC 通信: 基于 'fastmcp' 框架，默认支持 JSON-RPC 协议与客户端通信。
Stdio 传输协议: 服务器配置为使用 'stdio' 作为传输协议，方便本地客户端连接。
会话管理和能力声明: 'fastmcp' 框架处理了基本的会话管理和能力声明，虽然在代码中没有显式体现，但框架底层已支持。

安装步骤

安装 uv: 如果尚未安装 'uv'，请根据仓库 README 中的命令安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装后重启终端。

创建项目并安装依赖:

uv init content-database-mcp
cd content-database-mcp
uv venv
source .venv/bin/activate
uv add "mcp[cli]" httpx notion-client python-dotenv
touch main.py notion_utils.py
mkdir checkpoints

复制代码:
- 将 'notion_utils.py', 'checkpoints/checkpoint-3.py' 的代码内容分别复制到项目根目录的 'notion_utils.py' 和 'checkpoints/checkpoint-3.py' (并重命名为 'main.py') 文件中。
- 可选地，你也可以从 'checkpoints' 目录中选择其他检查点文件 ('checkpoint-1.py', 'checkpoint-2.py') 作为 'main.py' 的内容，以体验不同阶段的功能。 checkpoint-3.py 提供了较为完整的功能实现。
配置 Notion API 密钥:
- 访问 Notion Integrations 创建 Notion API Token。
- 将你的集成添加到你的 Notion 数据库中。
- 在项目根目录下创建 '.env' 文件，并添加 Notion API Token：
```
# .env
NOTION_TOKEN=你的Notion-API-Token
DATABASE_ID=你的Notion数据库ID  # 需要替换为你的数据库ID
```
- 请务必替换 'DATABASE_ID' 为你实际使用的 Notion 数据库 ID。 你可以在 Notion 数据库页面的 URL 中找到数据库 ID。

服务器配置

为了让 MCP 客户端（如 Cursor 或 Claude）连接到此 MCP 服务器，你需要配置客户端的 MCP 设置。以下是 'mcp.json' 或 'claude_desktop_config.json' 中需要添加的服务器配置信息：

{
    "mcpServers": {
        "notion-content-database": {  // 服务器名称，可以自定义
            "command": "uv",         // 启动命令，这里使用 uv 运行器
            "args": [                // 启动参数
                "run",              // uv run 命令
                "main.py"           // 运行 main.py 文件 (或 checkpoints/checkpoint-3.py，取决于你使用的文件)
            ],
            "cwd": "/PATH/to/content-database-mcp" // MCP服务器的工作目录，请替换为你的项目路径
        }
    }
}

请注意：

'"cwd"' 字段需要替换为你的 'content-database-mcp' 项目的实际绝对路径。
'"notion-content-database"' 可以自定义为其他名称，作为你在客户端中识别此服务器的标识。

基本使用方法

启动 MCP 服务器: 在项目根目录下运行以下命令启动服务器：
```
uv run main.py
```
服务器启动后，会输出 'Starting MCP server...'。
配置并连接 MCP 客户端: 根据你的 MCP 客户端（如 Cursor 或 Claude）的文档，配置并添加上面提供的服务器配置信息。
通过客户端调用工具: 在客户端中，你可以通过自然语言指令或特定命令来调用服务器提供的工具，例如：
- 在 Cursor 中，你可以使用 '@tool find_posts' 来调用 'find_posts' 工具。
- 工具的具体参数 (如 'platform', 'title' 等) 需要根据工具的定义在客户端中提供。例如，'@tool find_posts platform:Twitter'。
可用的工具包括 (基于 'checkpoint-3.py'):
- 'find_posts(platform: str)': 根据平台查找文章。平台参数 'platform' 必须是 "Twitter", "LinkedIn", "Blog" 中的一个。
- 'create_post(title: str, platform: str, status: str, tags: list[str], emoji: str)': 创建新的文章。参数包括标题 'title'、平台 'platform' ("Twitter", "LinkedIn", "Blog")、状态 'status' ("Idea", "Draft", "In Review", "Published")、标签列表 'tags' 和 emoji 表情符号 'emoji'。
- 'add_content_to_post(id: str, content: str)': 向指定 ID 的文章添加内容。参数包括文章的页面 ID 'id' 和要添加的内容 'content'。
请注意： 你需要将 '<ADD_YOUR_DATABASE_ID>' 替换为你的 Notion 数据库 ID，并在 '.env' 文件中正确配置 'NOTION_TOKEN' 和 'DATABASE_ID'。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息