Notebook Convert MCP

Jupyter Markdown MCP服务器

🎉 现在使用TypeScript！ 1.3.0版本是一个完整的TypeScript重写版本。不需要Python！ 📢 迁移通知：此包以前已命名 notebook-convert-mcp。如果您安装了旧软件包，请卸载并安装 jupyter-markdown-mcp 相反。

用于无缝Jupyter Notebook的原生TypeScript MCP服务器↔ Markdown转换，完美保存细胞。

特性

为什么是这个工具？

问题：Jupyter Notebook包含大量元数据，淹没了AI分析：

• 代码执行结果（通常为数百行）
• Base64编码图像
• 内核信息、单元格ID、输出元数据
• 人工智能模型难以专注于实际内容

解决方案：用于AI友好分析的干净转换：

• 笔记本→ 标记语言：删除所有元数据，只保留代码和标记内容
• 标记语言→ 笔记本：需要时转换回可执行笔记本

安装

快速安装（推荐）

# Install globally
npm install -g jupyter-markdown-mcp

# Run the installer
jupyter-markdown-mcp install

就是这样！ 不需要Python——纯TypeScript实现。

Claude代码CLI安装

选项1：使用NPX（无需安装）

claude mcp add --scope user jupyter-markdown-mcp -- npx jupyter-markdown-mcp@latest

选项2：使用NPM全局安装

# Install globally first
npm install -g jupyter-markdown-mcp

# Then add to Claude Code CLI
claude mcp add --scope user jupyter-markdown-mcp -- jupyter-markdown-mcp

手动安装

1.安装依赖项

cd "{YOUR_PROJECT_PATH}/jupyter-markdown-mcp"
npm install
npm run build

不需要Python依赖！ 使用TypeScript和Node.js构建。

2.AI CLI配置

克劳德代码CLI

macOS

~/.config/claude-code/claude_desktop_config.json:

{
  "mcpServers": {
    "jupyter-markdown": {
      "command": "node",
      "args": [
        "/{YOUR_PROJECT_PATH}/jupyter-markdown-mcp/dist/index.js"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

视窗

%APPDATA%\\Claude\\claude_desktop_config.json:

{
  "mcpServers": {
    "jupyter-markdown": {
      "command": "node",
      "args": [
        "C:\\\\{YOUR_PROJECT_PATH}\\\\jupyter-markdown-mcp\\\\dist\\\\index.js"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

3.重新启动AI CLI

成功确认：

🟢 jupyter-markdown - Connected (2 tools cached)
  convert_notebook, convert_markdown

验证安装

# Check installed version
npm list -g jupyter-markdown-mcp

# Verify MCP connection
claude mcp list
# Should show: jupyter-markdown-mcp - ✓ Connected

使用示例

笔记本→ Markdown（人工智能分析）

Convert all notebooks in the project folder to markdown for AI analysis.
Use convert_notebook to convert .ipynb files to clean markdown format.

发生了什么：

• 删除所有执行输出和元数据
• 将代码单元格转换为python块
• 按原样保存标记单元格
• 结果：干净、AI友好的标记文件

标记语言→ 笔记本电脑（开发）

Convert markdown document back to executable notebook.
Use convert_markdown to convert tutorial.md into a working notebook.

发生了什么：

• 自动检测python代码块
• 将代码块转换为可执行代码单元
• 将其他内容转换为标记单元格
• 结果：功能齐全的Jupyter笔记本

实用工作流程

用于机器学习项目

# 1. Convert notebooks to markdown for AI analysis
convert_notebook(
  source_path="/{YOUR_PROJECT_PATH}/analysis_notebook.ipynb",
  output_dir="/{YOUR_PROJECT_PATH}/markdown_docs/"
)

# 2. AI analyzes clean markdown (no metadata noise)
# 3. Modify/improve content with AI help

# 4. Convert back to executable notebook
convert_markdown(
  source_path="/{YOUR_PROJECT_PATH}/markdown_docs/improved_analysis.md", 
  output_dir="/{YOUR_PROJECT_PATH}/notebooks/"
)

益处

• 清洁人工智能分析：无元数据干扰
• 双向：双向无缝转换
• 保存内容：保持代码和标记的完整性
• 通用：适用于所有平台（macOS、Windows、Linux）

故障排除

Node.js版本

# Check Node.js version (requires v14 or higher)
node --version

# Verify installation
node -e "console.log('Node.js OK')"

构建问题

# Rebuild if needed
npm run build

# Check build output
ls dist/

路径配置

替换 {YOUR_PROJECT_PATH} 根据您的实际路径：

macOS/Linux示例

• /Users/YourName/Projects/mcp-servers
• /home/username/development/mcp-servers

Windows示例

• C:\\Users\\YourName\\Projects\\mcp-servers
• D:\\Development\\mcp-servers

更新日志

看 更改日志.md 查看详细的版本历史。

最新版本：1.3.0（2025-01-20）

• 完全重写TypeScript -不需要Python！
• 本地性能 -使用Node.js执行速度更快
• 类型安全性 -完整的TypeScript类型定义
• 添加：单元格边界标记(``)维持细胞结构
• 改进的：增强了从标记到笔记本的解析，以尊重单元格边界
• 结果：完美的往返转换，无需单元格合并

版本1.1.2

• 具有基本转换功能的初始稳定版本

______________________________________________________________________

聚焦：简单、可靠的Jupyter笔记本↔ Markdown转换用于AI增强的开发工作流程。