wolai 笔记 官方 MCP 协议的 macOS 适配工具包，让你在终端、Python 脚本、AI Agent（Claude Code 等）里读写 wolai 文档。
📌 原仓库
cizixiu/wolai-mcp-skill仅支持 Windows PowerShell。本项目把它适配到 macOS（zsh + Python + curl），并加入 多 Token Profile 切换、Excel 导出、图片下载 等扩展能力。
- 🍎 macOS 原生 — zsh / curl / Python，无 PowerShell 依赖
- 🔑 多 Profile — 一条命令在多个 wolai App / 空间之间切换
- 📖 读 — 大纲、章节、块树、子页面层级、表格、图片（带签名下载链接）
- ✍️ 写 — 创建文档、插入块、追加章节、改写内容、删除（推到回收站）
- 📊 Excel 导出 — wolai 表格 →
.xlsx，保留列宽 / 样式 / 筛选 / 冻结 - 🤖 AI 友好 — 提供 Claude Code Skill 文件，开箱即用
- 🪶 极简依赖 — Python
requests+openpyxl（仅导出 Excel 需要）
打开 wolai 笔记 → 个人设置 → MCP 接入 → 创建 Token（以 sk- 开头）。
💡 每个 Token 绑定一个 wolai App，访问范围 = 该 App 被加为协作者的页面树。
git clone https://github.com/<your-name>/wolai-mcp-macos.git
cd wolai-mcp-macos
./install.shinstall.sh 会：
- 把
shell/wolai.sh链接到~/.wolai/wolai.sh并写入~/.zshrc - 提示你输入 Token 写到
~/.wolai/tokens.env - 把 Skill 文件链接到
~/.claude/skills/wolai-mcp/（如目录存在）
也可以手动安装：
mkdir -p ~/.wolai
cp shell/wolai.sh ~/.wolai/
echo 'export WOLAI_TOKEN_DEFAULT="sk-你的Token"' > ~/.wolai/tokens.env
echo '[ -f ~/.wolai/wolai.sh ] && source ~/.wolai/wolai.sh' >> ~/.zshrc
source ~/.zshrcwolai_profiles # 列出所有 profile
wolai_use default # 切换 profile
wolai_call list_docs '{"limit":10}' # 列顶级文档
wolai_call get_page_outline '{"page_id":"xxx"}' # 读大纲或在 Python 里：
from wolai_mcp import invoke, search_docs, get_page_outline
for p in search_docs("会议纪要", limit=5):
print(p["id"], p["title"])# 把第二个 Token 加到 ~/.wolai/tokens.env
echo 'export WOLAI_TOKEN_PERSONAL="sk-另一个Token"' >> ~/.wolai/tokens.env
# 切换
wolai_use personal
wolai_use default| 命令 | 作用 |
|---|---|
wolai_use <profile> |
切换 token profile |
wolai_profiles |
查看所有 profile 与当前激活项 |
wolai_call <tool> <json> |
调用任意 MCP 工具，自动处理 SSE 解析 |
wolai_tools |
列出当前账号可用的 MCP 工具 |
wolai_outline <page_id> |
拉取页面大纲（彩色输出） |
wolai_export_xlsx <page_id> <out.xlsx> |
把页面里的表格导成 Excel |
wolai_dl_images <page_id> <dir> |
下载页面中的所有图片 |
| 类别 | 工具 |
|---|---|
| 文档 | list_docs get_doc create_doc update_doc delete_doc search_docs list_builtin_covers |
| 大纲 / 章节 | get_page_outline get_section_content locate_section move_section rewrite_section insert_under_heading delete_section |
| 块 | get_page_blocks get_block create_block insert_blocks_relative patch_block_content replace_block update_block delete_block |
| 布局 | create_column_layout |
详细参数与块类型示例：docs/api.md
把 skills/wolai-mcp/SKILL.md 链接到 ~/.claude/skills/wolai-mcp/SKILL.md，Claude Code 会自动识别。install.sh 已处理。
之后直接对 Claude 说：「看一下 https://www.wolai.com/xxx 这个页面」「把这张表导出成 Excel」即可。
wolai-mcp-macos/
├── README.md # 你正在看的文件
├── LICENSE # MIT
├── install.sh # 一键安装
├── shell/
│ └── wolai.sh # zsh 函数库
├── python/
│ ├── wolai_mcp.py # Python SDK
│ ├── export_xlsx.py # 表格 → Excel
│ └── download_images.py # 图片下载
├── skills/
│ └── wolai-mcp/
│ └── SKILL.md # Claude Code Skill
├── examples/
│ ├── basic_read.py
│ ├── create_page.py
│ └── append_blocks.py
└── docs/
├── api.md # 工具与参数详解
└── troubleshooting.md
Q：为什么 list_docs 返回空？
A：当前 Token 绑定的 App 没有被加为任何顶级页面的协作者。去 wolai 把目标页面 / 整个空间加这个 App 为协作者。
Q：报「块不存在于应用所属空间」 A：同上，访问的页面不在 Token 的授权范围内。换 Token 或扩授权。
Q：macOS GUI 应用（如 Claude Code 桌面版）读不到 Token
A：GUI 应用不读 ~/.zshrc。运行 launchctl setenv WOLAI_MCP_TOKEN "sk-..." 让 GUI 应用也能拿到。
- Token 等价访问凭证，不要提交到仓库或公开渠道
~/.wolai/tokens.env默认权限 600- 涉及账号 / 密码列的表格，导出时自动提醒用户
MIT — 见 LICENSE。
源 Skill 协议来自 cizixiu/wolai-mcp-skill。
- wolai — 提供官方 MCP 协议
cizixiu/wolai-mcp-skill— 原 Windows 版 Skill- Anthropic Claude Code — Skill 系统
PRs welcome. 有问题开 issue。