TimeVerse 3D Printer MCP Server

3D 打印机控制 MCP 服务器 — 支持 7 种通讯协议，提供实时状态监控、G-Code 处理、切片集成、网络发现等功能。通过 32 个 MCP 工具覆盖 3D 打印全生命周期管理。

目录

• 功能特性
• 快速开始
• 安装方式
  • 方式一：通过 uvx 安装（推荐）
  • 方式二：通过 pip 安装
  • 方式三：直接 Python 运行
• 凭证配置指南
  • 方法 A：配置文件（推荐）
  • 方法 B：环境变量
  • 方法 C：工具调用时传入
• MCP 客户端配置
  • uvx 模式
  • pip 模式
  • Python 直接运行模式
• 工具列表
  • 发现工具 (3 个)
  • 打印工具 (7 个)
  • 状态查询 (4 个)
  • 文件管理 (4 个)
  • G-Code 指令 (7 个)
  • 切片工具 (3 个)
  • 管理工具 (4 个)
• 传输协议说明
• 项目结构
• 环境变量参考

功能特性

• 7 种传输协议：USB 串口、OctoPrint REST API、Moonraker (Klipper)、Duet Web Control、Repetier Server、Bambu Lab MQTT、Raw TCP
• 32 个 MCP 工具：覆盖发现、状态、打印、文件管理、G-Code 控制、切片、打印机管理
• 智能路由：根据打印机类型自动选择最佳传输协议
• G-Code 安全校验：内置校验器检查温度、速度、流量等安全限制
• 多切片器集成：支持 PrusaSlicer、CuraEngine、OrcaSlicer，内置 6 个预设配置
• 网络发现：mDNS/Bonjour + 子网端口扫描自动发现局域网打印机
• 灵活的凭证系统：配置文件、环境变量、显式参数三种配置方式

快速开始

# 1. 安装
pip install -e .

# 2. 配置凭证（见凭证配置章节）
# 创建 timeverse-3dprinter.config.json 或设置环境变量

# 3. 启动 MCP 服务器
timeverse-3dprinter-mcp

安装方式

方式一：通过 uvx 安装（推荐）

uvx 是 Astral 提供的快速 Python 包运行工具：

# 直接运行（无需安装）
uvx timeverse-3dprinter-mcp

# 或全局安装后运行
uv tool install timeverse-3dprinter-mcp
uvx timeverse-3dprinter-mcp

从本地源码运行：

uvx --from . timeverse-3dprinter-mcp

方式二：通过 pip 安装

# 从 PyPI 安装
pip install timeverse-3dprinter-mcp

# 从本地源码安装
pip install -e .

# 启动服务器
timeverse-3dprinter-mcp

方式三：直接 Python 运行

# 克隆/下载源码后
cd timeverse-3dprinter-mcp

# 直接运行（无需安装）
python -m timeverse_3dprinter_mcp.server

# 或先安装依赖再运行
pip install mcp pyserial httpx websockets paho-mqtt zeroconf trimesh
python -m timeverse_3dprinter_mcp.server

凭证配置指南

远程打印需要认证凭证（API 密钥、访问码等）。不同传输协议需要的凭证如下：

凭证优先级（高 → 低）：显式传入参数 > 配置文件 > 环境变量

方法 A：配置文件（推荐）

在当前工作目录下创建 timeverse-3dprinter.config.json，或在用户目录 ~/.timeverse-3dprinter/config.json 创建：

{
  "printers": {
    "octopi": {
      "host": "192.168.1.100",
      "port": 5000,
      "transport": "octoprint",
      "api_key": "你的 OctoPrint API 密钥"
    },
    "klipper_box": {
      "host": "192.168.1.101",
      "port": 7125,
      "transport": "moonraker",
      "api_key": "你的 Moonraker API 密钥"
    },
    "bambu_x1": {
      "host": "192.168.1.102",
      "transport": "bambu",
      "serial_number": "打印机序列号",
      "access_code": "12345678"
    },
    "repetier_printer": {
      "host": "192.168.1.103",
      "port": 3344,
      "transport": "repetier",
      "api_key": "你的 Repetier API 密钥"
    }
  },
  "defaults": {
    "api_key": "",
    "username": "",
    "password": ""
  }
}

配置文件搜索顺序：

1. ./timeverse-3dprinter.config.json（当前目录）
2. ~/.timeverse-3dprinter/config.json（用户目录）

方法 B：环境变量

启动服务器前设置环境变量，或在 MCP 客户端配置的 env 字段中设置：

# Windows PowerShell
$env:TIMEVERSE_3DPRINTER_API_KEY = "你的全局 API 密钥"
$env:TIMEVERSE_3DPRINTER_USERNAME = "用户名"
$env:TIMEVERSE_3DPRINTER_PASSWORD = "密码"

# 按打印机名设置（将 MY_PRINTER 替换为实际打印机名）
$env:TIMEVERSE_3DPRINTER_MY_PRINTER_API_KEY = "打印机专用 API 密钥"
$env:TIMEVERSE_3DPRINTER_MY_PRINTER_ACCESS_CODE = "打印机访问码"
$env:TIMEVERSE_3DPRINTER_MY_PRINTER_SERIAL_NUMBER = "打印机序列号"

# Bambu Lab 专用
$env:TIMEVERSE_3DPRINTER_BAMBU_SERIAL_NUMBER = "Bambu 序列号"
$env:TIMEVERSE_3DPRINTER_BAMBU_ACCESS_CODE = "Bambu 访问码"

# Linux/macOS
export TIMEVERSE_3DPRINTER_API_KEY="你的全局 API 密钥"
export TIMEVERSE_3DPRINTER_BAMBU_SERIAL_NUMBER="Bambu 序列号"
export TIMEVERSE_3DPRINTER_BAMBU_ACCESS_CODE="Bambu 访问码"

方法 C：工具调用时传入

所有涉及远程连接的 28 个 MCP 工具都支持以下可选参数：

示例：

# 在 MCP 客户端中调用工具时传入凭证
send_gcode_tool(
    printer="192.168.1.100",
    commands="M105",
    transport="octoprint",
    api_key="你的 OctoPrint API 密钥"
)

print_file_tool(
    file_path="model.gcode",
    printer="192.168.1.100",
    transport="octoprint",
    api_key="你的 OctoPrint API 密钥"
)

get_printer_status_tool(
    printer="192.168.1.102",
    transport="bambu",
    serial_number="BAMBU序列号",
    access_code="12345678"
)

MCP 客户端配置

uvx 模式

{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "uvx",
      "args": ["timeverse-3dprinter-mcp"],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 API 密钥",
        "TIMEVERSE_3DPRINTER_BAMBU_SERIAL_NUMBER": "Bambu 序列号",
        "TIMEVERSE_3DPRINTER_BAMBU_ACCESS_CODE": "Bambu 访问码"
      }
    }
  }
}

pip 模式

{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "timeverse-3dprinter-mcp",
      "args": [],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 API 密钥"
      }
    }
  }
}

Python 直接运行模式

{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "python",
      "args": ["-m", "timeverse_3dprinter_mcp.server"],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 API 密钥",
        "TIMEVERSE_3DPRINTER_LOG_LEVEL": "info"
      }
    }
  }
}

通过 uvx 从本地源码运行：

{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "uvx",
      "args": ["--from", "/path/to/timeverse-3dprinter-mcp", "timeverse-3dprinter-mcp"],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 API 密钥"
      }
    }
  }
}

AI 客户端配置示例

TimeVerse Studio

在 TimeVerse Studio 的 MCP 配置界面中添加以下配置：

{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "uvx",
      "args": ["timeverse-3dprinter-mcp"],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 OctoPrint API 密钥",
        "TIMEVERSE_3DPRINTER_BAMBU_SERIAL_NUMBER": "Bambu 打印机序列号",
        "TIMEVERSE_3DPRINTER_BAMBU_ACCESS_CODE": "Bambu 局域网访问码"
      },
      "description": "3D 打印机控制 MCP 服务器"
    }
  }
}

Claude Desktop

将以下配置添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "uvx",
      "args": ["timeverse-3dprinter-mcp"],
      "env": {
        "TIMEVERSE_3DPRINTER_API_KEY": "你的 OctoPrint API 密钥"
      }
    }
  }
}

Cursor / Windsurf

在 MCP 配置文件中添加：

{
  "mcpServers": {
    "timeverse-3dprinter": {
      "command": "uvx",
      "args": ["timeverse-3dprinter-mcp"]
    }
  }
}

注：如果项目未发布到 PyPI，将 args 中的包名替换为本地路径：["--from", "/path/to/timeverse-3dprinter-mcp", "timeverse-3dprinter-mcp"]

VS Code (通过 Continue 扩展)

在 ~/.continue/config.json 中添加：

{
  "experimental": {
    "mcpServers": {
      "timeverse-3dprinter": {
        "command": "uvx",
        "args": ["timeverse-3dprinter-mcp"],
        "env": {
          "TIMEVERSE_3DPRINTER_API_KEY": "你的 API 密钥"
        }
      }
    }
  }
}

工具列表

发现工具 (3 个)

打印工具 (7 个)

状态查询 (4 个)

文件管理 (4 个)

G-Code 指令 (7 个)

切片工具 (3 个)

管理工具 (4 个)

传输协议说明

项目结构

timeverse-3dprinter-mcp/
├── pyproject.toml
├── src/timeverse_3dprinter_mcp/
│   ├── server.py                  # MCP 服务器入口（32 个工具）
│   ├── tools/                     # MCP 工具定义（6 个模块）
│   │   ├── discovery.py
│   │   ├── printing.py
│   │   ├── status.py
│   │   ├── files.py
│   │   ├── gcode.py
│   │   └── slicing.py
│   ├── transports/                # 传输层（7 种协议）
│   │   ├── base.py                # 抽象基类
│   │   ├── router.py              # 传输路由器
│   │   ├── serial_transport.py
│   │   ├── octoprint_transport.py
│   │   ├── moonraker_transport.py
│   │   ├── duet_transport.py
│   │   ├── repetier_transport.py
│   │   ├── bambu_transport.py
│   │   └── raw_tcp.py
│   ├── gcode/                     # G-Code 处理
│   │   ├── builder.py             # 指令构建器
│   │   ├── parser.py              # 文件解析器
│   │   ├── validator.py           # 安全校验
│   │   └── temp_monitor.py        # 温度监控
│   ├── slicing/                   # 切片器集成
│   │   ├── base.py
│   │   ├── prusaslicer.py
│   │   ├── cura_engine.py
│   │   ├── orcaslicer.py
│   │   └── profiles.py
│   ├── discovery/                 # USB/网络发现
│   │   ├── serial_scan.py
│   │   ├── mdns_discovery.py
│   │   └── network_scan.py
│   └── utils/                     # 工具模块
│       ├── config.py              # 凭证/配置管理
│       ├── types.py               # 数据模型
│       ├── errors.py              # 错误处理（21 种错误码）
│       ├── logger.py              # 日志
│       └── platform.py            # 平台检测
└── tests/

环境变量参考

许可证

MIT