内容
# notebookllm
[](https://pypi.org/project/notebookllm)
[](https://pepy.tech/projects/notebookllm)
> **⚡ 统一包 — 一次安装，即可使用全部功能**
>
> 独立的 `notebookllm-mcp` 服务器已完全集成到核心 `notebookllm` 包中。Python 库和 MCP 服务器现在一起提供，只需一次 `pip install` 即可，无需额外配置。旧的 `notebookllm-mcp` 包已弃用。安装 `notebookllm[mcp]` 即可获取全部功能。
**用于 AI 代理（Claude Code、Cursor、GitHub Copilot、Claude Desktop、VS Code、Zed 等）的 Jupyter 笔记本转换、检查和优化工具。**
`notebookllm` 是笔记本操作的瑞士军刀。它将笔记本转换为干净、适合代理的纯文本格式 — 可减少高达 **80%** 的 token 使用量 — 并通过单一的统一 API 读取/写入 **8+ 种格式**。可从命令行、Python 库或作为 MCP 服务器用于 AI 代理集成。
---
## 主要功能
- **8+ 种笔记本格式** — 加载和保存 `.ipynb`、百分比（`# %%`）、Quarto（`.qmd`）、Markdown（`.md`）、Marimo（`.py`）、R Markdown（`.Rmd`）、Deepnote（`.deepnote`）和扁平脚本。统一的 API 来管理它们。
- **AI 代理优化输出** — 删除 JSON 噪音、元数据和 base64 块。生成干净的文本，以便 AI 代理可以有效推理。四种详细程度模式：`minimal`、`standard`、`full` 和 `token-budget`。
- **智能 token 预算** — 自动删除优先级最低的单元格以适应 token 限制。Markdown（解释性）→ 带输出的代码 → 纯代码（优先删除）。
- **Token 计数** — 通过 tiktoken（GPT-4 `cl100k_base`）或内置启发式回落进行每个笔记本和每个单元格的 token 测量。
- **智能输出摘要** — DataFrame 获取形状/列摘要，图像获取大小元数据，跟踪压缩到最后一行。
- **批量转换** — 一次命令转换整个笔记本目录。
- **单元格操作** — 以编程方式添加、编辑、删除、移动、搜索和执行单元格。
- **流式处理** — 通过 ijson 流式处理处理大于 10 MB 的笔记本（单元格逐一处理，无内存激增）。
- **MCP 服务器** — 将所有操作公开为 MCP 工具、资源和提示，供任何 MCP 兼容的 AI 代理客户端（Claude Desktop、VS Code、Zed、Cursor、Claude Code）使用。
- **验证和原子写入** — 检测孤立的输出、空单元格和无效类型。通过 temp-file + rename 实现崩溃安全的 文件保存。
---
## 快速入门
```bash
pip install notebookllm[cli]
# 将笔记本转换为适合代理的文本
notebookllm convert notebook.ipynb
# 在不同格式之间转换
notebookllm convert notebook.ipynb -o output.py -f percent
# 计数 token
notebookllm tokens notebook.ipynb --breakdown
# 检查笔记本结构
notebookllm inspect notebook.ipynb
```
```python
from notebookllm import load_file
# 加载任意笔记本格式 — 自动检测
doc = load_file("notebook.ipynb")
# 转换为适合 AI 代理的文本
print(doc.to_text()) # minimal（默认）
print(doc.to_text(mode="token-budget", max_tokens=2000)) # 预算模式
```
---
## 为什么选择 notebookllm？
原始的 `.ipynb` 文件会浪费 AI 代理的上下文。JSON 结构、执行元数据和 base64 编码的图像输出会消耗 token 而不增加价值。`notebookllm` 删除了所有噪音，生成干净、结构化的文本，以便代理可以有效推理。
但它不仅仅是一次转换。`notebookllm` 是一个 **双向笔记本工具包**：它读取、写入、编辑、搜索、执行和转换笔记本，支持 8+ 种格式。无论您是将笔记本输入 Claude Code、构建 VS Code 扩展还是自动化数据管道，`notebookllm` 都能满足您的需求。
---
## 安装
> **从 `notebookllm-mcp` 迁移？** 单独的 MCP 包现已弃用。所有功能都已内置。只需 `pip install notebookllm[mcp]`。
```bash
pip install notebookllm # 核心：格式转换、流式处理、执行
pip install notebookllm[cli] # + 命令行界面（click、rich tables、语法高亮）
pip install notebookllm[mcp] # + 用于 AI 代理集成的 MCP 服务器
pip install notebookllm[token] # + 通过 tiktoken 进行准确的 token 计数
pip install notebookllm[all] # 所有功能（CLI + MCP + token）
```
**依赖项分解：**
| 额外 | 您获得的内容 |
|-------|-------------|
| *(base)* | `nbformat`、`jupyter_client`、`ijson`、`pyyaml` — 格式转换、流式处理、单元格执行 |
| `[cli]` | `click`、`rich` — 带有格式化输出的命令行界面 |
| `[mcp]` | `mcp[cli]` — 用于 AI 代理客户端的 MCP 服务器 |
| `[token]` | `tiktoken` — GPT-4 token 计数（如果没有，则使用 `len(text)/4` 启发式，±20%） |
---
## 命令行界面参考
### `notebookllm convert`
在不同格式之间转换笔记本或转换为适合代理的文本。
```bash
# 单个文件转换为优化的代理文本（stdout）
notebookllm convert notebook.ipynb
# 单个文件转换为特定格式
notebookllm convert notebook.ipynb -o output.py -f percent
notebookllm convert notebook.ipynb -o output.qmd -f quarto
# 输出详细程度
notebookllm convert notebook.ipynb # minimal（默认）
notebookllm convert notebook.ipynb -m standard # + 执行计数、标签
notebookllm convert notebook.ipynb -m full # + 单元格输出
# 批量：多个文件到 stdout
notebookllm convert a.ipynb b.qmd c.py
# 批量：多个文件到目录（自动命名）
notebookllm convert *.ipynb --outdir ./out
notebookllm convert a.ipynb b.qmd --outdir ./out -f markdown
```
### `notebookllm inspect`
显示笔记本结构 — 格式、语言、单元格计数和带有预览的格式化单元格表。
```bash
notebookllm inspect notebook.ipynb
```
### `notebookllm search`
按内容（不区分大小写的子字符串匹配）搜索单元格。按类型使用 `-t` 进行筛选。
```bash
notebookllm search notebook.ipynb "import pandas"
notebookllm search notebook.ipynb "def train" -t code
```
### `notebookllm get`
通过 0-based 索引提取单个单元格。包含丰富的语法高亮。
```bash
notebookllm get notebook.ipynb 3
```
### `notebookllm tokens`
估计 token 使用量。使用 tiktoken 时，会回落到启发式算法。
```bash
notebookllm tokens notebook.ipynb # 总 token
notebookllm tokens notebook.ipynb --breakdown # 每个单元格的表格
notebookllm tokens notebook.ipynb -m full # 计数输出
```
### `notebookllm server`
启动用于 AI 代理集成的 MCP 服务器。
```bash
notebookllm server # stdio（默认 — Claude Desktop、VS Code、Zed）
notebookllm server --transport sse # SSE（基于 HTTP 的连接）
```
---
## Python API
### 加载和保存
```python
from notebookllm import NotebookDocument, load_file, dump_file, loads_text
# 加载 — 自动从扩展名检测格式
doc = load_file("notebook.ipynb")
doc = load_file("analysis.qmd")
doc = load_file("report.Rmd")
# 从字符串加载并自动检测
doc = loads_text("# %% [code]\nprint('hi')\n") # 自动检测为 "percent"
# 显式格式
doc = loads_text(text, source_format="quarto")
# 便捷类方法
doc = NotebookDocument.from_file("notebook.ipynb")
doc = NotebookDocument.from_text(text, source_format="quarto")
# 保存 — 自动从扩展名检测格式
doc.to_file("output.ipynb")
doc.to_file("output.py", fmt="percent")
# 序列化/反序列化（CIR JSON）
json_str = doc.to_json()
restored = NotebookDocument.from_json(json_str)
```
### 转换为适合代理的文本
```python
from notebookllm import OutputMode
# 四种输出详细程度模式
text = doc.to_text() # minimal（默认）
text = doc.to_text(mode=OutputMode.STANDARD) # + 执行计数、标签
text = doc.to_text(mode=OutputMode.FULL) # + 单元格输出
text = doc.to_text(mode="token-budget", max_tokens=5000) # 预算模式
```
**输出示例：
```python
# MINIMAL — 干净、token 高效
# %% [code]
import pandas as pd
df = pd.read_csv("data.csv")
# STANDARD — 包括元数据
# %% [code]
# exec_count: 3
# tags: preprocessing, cleaning
df = df.dropna()
# FULL — 包括输出
# %% [code]
print(df.head())
# --- 输出 ---
# [stdout] col1 col2
# 0 1 2
```
### Token 计数
```python
from notebookllm import tokenize_notebook, count_tokens
# 笔记本级 token 分析
report = tokenize_notebook(doc, mode="minimal")
print(report.token_summary) # "Total: 420 tokens across 8 cells (minimal mode)"
for ct in report.cell_tokens:
print(f" [{ct.cell_index}] {ct.cell_type}: {ct.tokens} tokens — {ct.preview}")
# 单个字符串
n = count_tokens("hello world") # 2 tokens（tiktoken）或 3（启发式算法）
# 文档上的便捷方法
report = doc.token_breakdown(mode="minimal")
```
### 单元格操作
```python
from notebookllm import Cell, CellType
# 添加单元格
doc.add_cell(Cell(cell_type=CellType.CODE, source="x = 1"))
doc.add_cell(Cell(cell_type=CellType.MARKDOWN, source="# Title"), position=0)
# 编辑
doc.edit_cell(0, source="x = 2")
doc.edit_cell(0, source="# New", cell_type=CellType.MARKDOWN)
# 删除和移动
doc.delete_cell(2)
doc.move_cell(from_index=0, to_index=2)
# 获取
cell = doc.get_cell(0)
print(cell.source, cell.cell_type, cell.execution_count)
```
### 搜索和筛选
```python
# 搜索并可选筛选类型
results = doc.search("import pandas", cell_type=CellType.CODE)
for idx, cell in results:
print(f"[{idx}] {cell.source[:60]}")
# 筛选
code_cells = doc.filter_cells(cell_type=CellType.CODE)
matches = doc.filter_cells(query="train")
```
### 检查
```python
print(len(doc.cells)) # 单元格计数
print(doc.source_format) # "ipynb", "percent", "quarto" 等
print(doc.language) # "python", "r" 等
print(doc.kernel_name) # "python3" 等
```
### 验证
```python
from notebookllm.utils.validation import validate_notebook
report = validate_notebook(doc)
print(report.summary) # "Validation passed." 或 "Validation found 2 errors, 3 warnings."
print(report.format_text()) # 人类可读的错误/警告列表
print(report.is_valid) # 如果没有错误，则为 True
```
---
## 支持的格式
| 扩展名 | 格式 | 加载 | 转储 |
|-----------|--------|:----:|:----:|
| `.ipynb` | Jupyter Notebook | ✅ | ✅ |
| `.py` | 百分比脚本（`# %%` 标记） | ✅ | ✅ |
| `.py` | Marimo（`@app.cell` 装饰器） | ✅ | ✅ |
| `.qmd` | Quarto 文档 | ✅ | ✅ |
| `.md` | 带有围栏代码块的 Markdown | ✅ | ✅ |
| `.Rmd` | R Markdown | ✅ | ✅ |
| `.deepnote` | Deepnote YAML 项目 | ✅ | ✅ |
| `.py` | 扁平脚本（单向导出） | ❌ | ✅ |
---
## 用于 AI 代理集成的 MCP 服务器
MCP 服务器公开了所有 notebookllm 操作，作为 MCP 工具、资源和提示。这让任何 MCP 兼容的 AI 代理客户端（Claude Desktop、VS Code、Zed、Cursor、Claude Code）都可以在您的 behalf 上操作笔记本。
### 设置
启动 MCP 服务器：
```bash
notebookllm server
```
### 配置
使用 ``uvx``（推荐）或 ``pip`` 和 ``python -m`` 配置您的 MCP 客户端。
#### 使用 uvx（零配置，无需手动安装）
``uvx`` 自动从 PyPI 获取 ``notebookllm`` 并在隔离环境中运行服务器。
**Claude Desktop** (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"notebookllm": {
"command": "uvx",
"args": ["notebookllm-server"]
}
}
}
```
要固定特定版本或额外功能：
```json
{
"mcpServers": {
"notebookllm": {
"command": "uvx",
"args": ["--from", "notebookllm[all]", "notebookllm-server"]
}
}
}
```
**VS Code** (`.vscode/mcp.json`)：
```json
{
"mcp": {
"servers": {
"notebookllm": {
"command": "uvx",
"args": ["notebookllm-server"]
}
}
}
}
```
**Zed** (`~/.config/zed/mcp.json`)：
```json
{
"notebookllm": {
"command": "uvx",
"args": ["notebookllm-server"]
}
}
```
#### 使用 pip（手动安装）
首先安装软件包，然后引用已安装的服务器模块：
```bash
pip install notebookllm[mcp]
```
**Claude Desktop** (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"notebookllm": {
"command": "python",
"args": ["-m", "notebookllm.mcp.server"]
}
}
}
```
**VS Code** (`.vscode/mcp.json`)：
```json
{
"mcp": {
"servers": {
"notebookllm": {
"command": "python",
"args": ["-m", "notebookllm.mcp.server"]
}
}
}
}
```
**Zed** (`~/.config/zed/mcp.json`)：
```json
{
"notebookllm": {
"command": "python",
"args": ["-m", "notebookllm.mcp.server"]
}
}
```
### 工具（共 26 个 — 20 个唯一 + 6 个别名）
| 主要名称 | 描述 | 是否破坏性 |
|-------------|-------------|:-----------:|
| `load` | 加载笔记本文件到新会话 | 否 |
| `create` | 创建空笔记本会话 | 否 |
| `list_sessions` | 列出所有活动会话 | 否 |
| `close_session` | 关闭会话并清理其内核 | 否 |
| `save` | 保存会话到文件 | 是 |
| `to_text` | 转换为适合代理的文本 | 否 |
| `list_cells` | 列出单元格索引、类型、预览 | 否 |
| `get_cell` | 通过索引获取单元格 | 否 |
| `add_cell` | 添加新单元格 | 否 |
| `edit_cell` | 编辑现有单元格 | 是 |
| `delete_cell` | 删除单元格 | 是 |
| `move_cell` | 移动单元格到新位置 | 否 |
| `search_cells` | 按内容搜索单元格 | 否 |
| `count_tokens` | 计算会话中的 token | 否 |
| `convert` | 将会话转换为另一种格式 | 否 |
| `execute` | 通过 Jupyter 内核执行代码单元格 | 是 |
| `execute_all` | 顺序执行所有代码单元格 | 是 |
| `list_kernels` | 列出可用的 Jupyter 内核 | 否 |
| `fingerprint` | 会话摘要（单元格、导入、函数） | 否 |
| `diff` | 使用统一的差异比较两个会话 | 否 |
**别名**（与旧版 `notebookllm-mcp` 向后兼容）：`load_notebook`、`create_notebook`、`save_notebook`、`convert_format`、`execute_cell`、`execute_all_cells`.
### 资源
| URI | 描述 |
|-----|-------------|
| `notebook://{session_id}` | 作为适合代理的文本的完整笔记本 |
| `notebook://{session_id}/cells` | 单元格列表，包含索引、类型、预览 |
| `notebook://{session_id}/cells/{index}` | 特定单元格按索引 |
### 提示
| 提示 | 描述 |
|--------|-------------|
| `summarize_notebook(session_id)` | 总结笔记本内容和目的 |
| `review_code(session_id)` | 审查笔记本中的代码质量 |
| `explain_notebook(session_id)` | 逐步解释笔记本 |
### 会话管理
MCP 服务器最多可容纳 **100 个并发会话**，并将其持久化到本地 SQLite 数据库 `~/.local/share/notebookllm/sessions.db`。会话在服务器重启后仍然存在。每个会话可选地拥有一个 Jupyter 内核用于代码执行。当达到限制时，会话会被逐出（按顺序，最旧的优先）。
---
## 代理技能
对于自主 AI 代理（Claude Code、Cursor、Claude Desktop、GitHub Copilot Workspaces），`notebookllm` 在 `skills/notebookllm/SKILL.md` 包含一个 **原生代理技能**。
此技能文档教导 AI 代理如何使用 `notebookllm` 在您的 behalf 上操作和检查笔记本。要装备您的代理：
1. 确保 `skills/` 目录可被您的代理访问
2. 或指示代理直接读取 `skills/notebookllm/SKILL.md`
该技能涵盖了：命令行命令、Python API 用法、输出模式、token 计数、格式转换和 MCP 服务器集成。
---
## 输出模式
控制 Agent 优化文本输出的详细程度：
| 模式 | 包含内容 | 最适合 |
|------|----------------|----------|
| `minimal` | `# %% [type]` 标记 + 源代码 | 代理输入 — 最干净、最节省 token |
| `standard` | 添加执行计数和元数据标签 | 了解笔记本执行历史 |
| `full` | 添加所有单元格输出（stdout、结果、错误） | 完整的笔记本状态分析 |
| `token-budget` | 删除优先级最低的单元格以适应 `max_tokens` | 严格的上下文窗口限制 |
**Token 预算优先级**（保留价值最高的单元格最长时间）：
1. Markdown 单元格（解释性 — 如果只剩一个，则永远不会删除）
2. 带输出的代码单元格（已执行、有结果）
3. 无输出的代码单元格（脚手架 — 优先删除）
---
## 输出摘要
当使用 `token-budget` 模式或 `summarize_outputs=True` 时，会自动压缩长且丰富的输出：
- **DataFrame**：从 ASCII 表示中提取形状和列名 — `# [DataFrame(1000, 5)] Columns: col1, col2, col3 (values hidden)`
- **图像**：MIME 类型和近似大小 — `# [Plot: image/png, ~42KB]`
- **跟踪信息**：仅最后一行 — `# [error] ValueError: invalid literal for int()`
- **长文本**：在 500 个字符处截断，并附有剩余说明
---
## 单元格执行
通过 MCP 服务器的 `execute` 和 `execute_all` 工具，使用 Jupyter 内核运行代码单元格。执行是异步和线程池的，以保持服务器响应。内核按需启动，每个会话一个，并在会话关闭时清理。
```bash
# 通过 MCP 服务器工具：
# execute(session_id="...", index=0)
# execute_all(session_id="...")
# list_kernels()
```
---
## 开发
```bash
git clone https://github.com/yasirrazaa/notebookllm.git
cd notebookllm
uv sync && uv pip install -e ".[dev]"
# 运行测试
uv run pytest
# 覆盖测试
uv run pytest --cov=notebookllm
# 运行基准测试
uv run pytest tests/benchmarks --benchmark-only
# 整理和类型检查
uv run ruff check .
uv run mypy notebookllm
# 构建文档
uv run sphinx-build -b html -E docs docs/_build
```
---
## 许可证
MIT — 参见 [LICENSE](LICENSE) 获取详细信息。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器