# Notion MCP 连接技能包

> HLDP://lighthouse/skills/notion-mcp-connect/SKILL.md
> 类型: 连接器技能包
> 适用: 新加坡面孔服务器 (BS-SG-002) 上的 MCP Server
> 铸渊 ICE-GL-ZY001 · D139 · 2026-06-22

---

## 这是什么

光湖的新加坡面孔服务器上已经运行着 AGE OS MCP Server（PM2 `age-os-mcp`，端口 3100）。
它内置了 Notion 客户端 `notion-client.js`，可以实现 brain_nodes ↔ Notion 双向同步。

**如果你的 Notion 连不上，通常是因为 `ZY_NOTION_TOKEN` 没有配置。**

这个技能包告诉你：
1. 如何创建 Notion Integration 获取 token
2. 如何配置到服务器上
3. 如何测试连接

---

## 配置 Notion Token

### 第一步 · 创建 Notion Integration

1. 打开 https://www.notion.so/my-integrations
2. 点击「New integration」
3. 名称: `光湖 · 桔子` (或你的名字)
4. 关联工作区: 选择你的 Notion 工作区
5. 类型: Internal
6. 创建后复制「Internal Integration Secret」→ 这就是 token

### 第二步 · 授权数据库

在 Notion 中打开你需要同步的数据库页面:
1. 点击右上角 `...` → Connections
2. 添加你刚创建的 integration
3. 每个需要读写的数据库都要授权

### 第三步 · 配置到服务器

Token 写到 MCP Server 的环境变量:

```bash
# SSH 到新加坡面孔服务器
ssh BS-SG-002

# 编辑环境变量文件
sudo nano /opt/age-os/.env.mcp

# 找到这一行:
# ZY_NOTION_TOKEN=

# 填入你的 token:
ZY_NOTION_TOKEN=secret_xxxxxxxxxxxxxxxxxxxxx
```

### 第四步 · 重启 MCP Server

```bash
pm2 restart age-os-mcp
pm2 logs age-os-mcp --lines 20
```

### 第五步 · 测试连接

```bash
curl -X POST http://127.0.0.1:3100/api/mcp/notion/test \
  -H "Content-Type: application/json" \
  -d '{}'
```

预期返回: `{"ok":true,"service":"notion","status":"connected"}`

---

## 已有的 Notion 数据库

MCP Server 已经配置了以下数据库（需要你在 Notion 中创建对应页面）:

| 用途 | 环境变量 |
|------|----------|
| 变更日志 | `ZY_NOTION_CHANGELOG_DB` |
| 收据 | `ZY_NOTION_RECEIPT_DB` |
| 系统日志 | `ZY_NOTION_SYSLOG_DB` |
| 认知运行时 | `ZY_NOTION_COGNITION_RUNTIME_DB` |
| 开发工单 | `ZY_NOTION_DEV_WORKORDER_DB` |
| 公告板 | `ZY_NOTION_BULLETIN_PAGE` |

每个数据库需要在 `.env.mcp` 中填入对应的数据库 ID（从 Notion URL 中复制）。

---

## 常见问题

**Q: 提示「ZY_NOTION_TOKEN 未配置」？**
A: Token 是空的。按上面步骤创建 Notion Integration。

**Q: 连上了但读不到数据？**
A: 检查数据库是否授权给了 integration（第二步）。

**Q: 怎么获取数据库 ID？**
A: 在 Notion 中打开数据库页面，URL 中的 32 位字符串就是 ID。
   例如: `notion.so/workspace/abc123def456...` → `abc123def456...`

---
铸渊 ICE-GL-ZY001 · D136+
⊢ MCP Server 代码已就绪 · 只差 token