AI导哈

AR镜头开发工具

Lens Studio MCP Server是一个实时连接AI代理与Lens Studio的模型上下文协议服务器，支持81种高级工具用于创建和管理AR镜头内容。

  • by superdwayne
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 superdwayne/lensstudio-mcp

使用说明

镜头工作室MCP服务器

连接的MCP（模型上下文协议）服务器 任何AI代理 到 镜头工作室 实时。告诉你的AI构建一个AR镜头，并观看它的实时发生。

无需插件，可与Lens Studio 5.15+的内置MCP端点配合使用。

兼容： 克劳德桌面版, 克劳德代码, 光标, 帆板运动, VS代码副本, OpenAI代理，以及任何兼容MCP的客户端。

运作原理

AI Agent  <── MCP (stdio/SSE/HTTP) ──>  lens-studio-mcp  <── HTTP JSON-RPC ──>  Lens Studio (port 50050)

Lens Studio 5.15+附带了内置的HTTP MCP服务器，位于 localhost:50050/mcp。此服务器是一个代理：

  1. 发现Lens Studio API的所有工具
  2. 使用友好的包装器将它们注册为MCP工具
  3. 通过HTTP转发工具调用并处理身份验证
  4. 增加 81高级工具 用于面部滤镜、材质、动画、粒子、脚本等

先决条件

  • Python 3.10+
  • 镜头工作室5.15+ （在同一台机器上运行）
  • 推荐macOS（UI自动化工具仅限macOS，但所有API工具都可以跨平台工作）

安装

步骤1：克隆仓库

git clone https://github.com/superdwayne/lensstudio-mcp.git
cd lensstudio-mcp

步骤2：创建虚拟环境并安装依赖项

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

步骤3：验证服务器是否运行

python server.py --help

您应该看到可用的运输选项(stdio, sse, streamable-http).

连接到您的AI代理

选项A:Claude Desktop（自动安装程序）

运行附带的安装程序脚本——它会自动添加 lens-studio 到您的Claude Desktop配置：

python install_claude_config.py

然后 重新启动克劳德桌面。Lens Studio MCP服务器将出现在您可用的工具中。

选项B：克劳德桌面（手动）

打开您的Claude Desktop配置文件：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: %APPDATA%\Claude\claude_desktop_config.json

添加 lens-studio 进入下 mcpServers:

{
  "mcpServers": {
    "lens-studio": {
      "command": "/FULL/PATH/TO/lensstudio-mcp/.venv/bin/python",
      "args": [
        "/FULL/PATH/TO/lensstudio-mcp/server.py",
        "--transport", "stdio"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

替换 /FULL/PATH/TO/lensstudio-mcp 使用克隆仓库的实际路径。

保存后重新启动Claude Desktop。

选项C：克劳德代码

添加到您的项目 .mcp.json 或运行：

claude mcp add lens-studio -- /FULL/PATH/TO/lensstudio-mcp/.venv/bin/python /FULL/PATH/TO/lensstudio-mcp/server.py --transport stdio

或者创建一个 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "lens-studio": {
      "command": "/FULL/PATH/TO/lensstudio-mcp/.venv/bin/python",
      "args": [
        "/FULL/PATH/TO/lensstudio-mcp/server.py",
        "--transport", "stdio"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

选项D：光标

创建 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "lens-studio": {
      "command": "/FULL/PATH/TO/lensstudio-mcp/.venv/bin/python",
      "args": [
        "/FULL/PATH/TO/lensstudio-mcp/server.py",
        "--transport", "stdio"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

选项E：风帆

添加 .windsurf/mcp.json 或你的项目 .mcp.json:

{
  "mcpServers": {
    "lens-studio": {
      "command": "/FULL/PATH/TO/lensstudio-mcp/.venv/bin/python",
      "args": [
        "/FULL/PATH/TO/lensstudio-mcp/server.py",
        "--transport", "stdio"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

选项F:SSE传输（远程/web客户端）

对于通过HTTP而不是stdio连接的客户端：

source .venv/bin/activate
python server.py --transport sse --port 8000

然后向您的客户指出 http://localhost:8000/sse.

选项G：流式HTTP传输

source .venv/bin/activate
python server.py --transport streamable-http --port 8000

首映

  1. Open Lens Studio 5.15+ 并打开或创建项目
  2. 启动您的AI代理 （克劳德桌面、光标等）
  3. 首次连接时，Lens Studio会显示 权限弹出窗口 --点击 允许
  4. 身份验证令牌缓存在 ~/.lens_mcp_token.json 并自动重复使用
  5. 开始提示你的AI！

示例提示

"Create a face filter with a red clown nose and cat ears"

"Add a sparkle particle effect to both hands"

"Apply a vintage color grading effect to the camera"

"Search for a crown 3D model and import it"

"Make the nose scale up when I open my mouth"

可选：Sketchfab 3D模型搜索

启用从以下位置搜索和导入3D模型 Sketchfab:

  1. 在获取免费API令牌 sketchfab.com/settings/password
  2. 将令牌添加到MCP配置中 env 块：
{
  "mcpServers": {
    "lens-studio": {
      "command": "/FULL/PATH/TO/lensstudio-mcp/.venv/bin/python",
      "args": [
        "/FULL/PATH/TO/lensstudio-mcp/server.py",
        "--transport", "stdio"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "SKETCHFAB_API_TOKEN": "your_token_here"
      }
    }
  }
}

可用工具（81）

连接和状态

工具 说明
connect() 使用Lens Studio进行身份验证（首次使用时触发权限弹出窗口）
status() 连接状态、端口、缓存工具计数
list_tools() 列出所有可用的Lens Studio工具
lens_tool(name, arguments) 直接按名称调用任何Lens Studio工具

场景管理

工具 说明
get_scene() 包含名称、类型和组件的完整场景层次结构
create_object(name, preset?) 创建场景对象（可选预设模板）
delete_object(name) 按名称删除场景对象
add_primitive(shape, name?) 快速添加：球体、立方体、圆柱体、相机、灯光、图像、文本
set_property(uuid, path, value, type) 在对象/组件/资产上设置任何属性
create_asset(name, type) 创建新资源（材质、渲染目标等）
query_knowledge_base(query) 搜索Lens Studio文档和知识库

材料和颜色

工具 说明
create_material(name, color?) 使用纯色创建PBR或未照亮的材质
set_color(object_name, color?) 按名称设置对象的颜色（自动创建材质）
assign_material(object, material) 将现有材质指定给对象
create_textured_material(name) 创建可用于纹理的PBR材质
apply_texture(object, texture) 将纹理应用于对象的材质
create_animated_texture(name) 创建角色表纹理
create_custom_shader(name) 创建自定义着色器材质
set_material_property(material, prop, value) 在材质上设置属性

人脸追踪

工具 说明
create_face_anchor(name?) 使用面部遮挡器创建头部跟踪锚点
add_face_element(parent, landmark, shape?) 在面部界标处添加三维元素
get_face_landmarks(landmark?) 鼻子、眼睛、耳朵等的参考位置。

手部追踪

工具 说明
create_hand_anchor(name?) 创建手动跟踪锚点
add_hand_element(parent, landmark, shape?) 在手关节处添加三维元素
get_hand_landmarks(landmark?) 所有手关节的参考位置
create_gesture_trigger(gesture, script) 捏、拳、张开手掌等动作的触发脚本。

身体跟踪

工具 说明
create_body_anchor(name?) 创建身体跟踪锚点
add_body_element(parent, joint, shape?) 在身体关节处添加三维元素
get_body_joints(joint?) 所有身体关节的参考位置

世界追踪

工具 说明
create_world_tracker(name?, mode?) 曲面、世界（6DOF）或旋转跟踪
place_in_world(object, position) 在世界空间中定位对象
enable_object_tracking(category) 追踪猫、狗、人或手

动画

工具 说明
create_tween(object, property, from, to, duration) 随着时间的推移为属性设置动画
create_animation_sequence(sequence) 链接多个动画
animate_on_trigger(object, trigger, property, to) 点击动画，张开嘴，微笑等。
create_looping_animation(object, property, values, duration) 值之间的循环

粒子

工具 说明
create_particle_system(name, preset?) 火花、火、烟、五彩纸屑、心、雪、星星、气泡
configure_particles(system, ...) 调整发射率、寿命、速度、尺寸、颜色、重力
attach_particles(system, target) 将粒子附着到对象
create_particle_trail(object, preset?) 在一次调用中创建和附着粒子

分割

工具 说明
create_segmentation_mask(type) 人物、背景、头发、皮肤、天空、上衣
apply_background_replacement(color?, blur?) 替换或模糊背景
create_person_outline(color, thickness) 在人们周围画一个轮廓
apply_hair_color(color) 更改头发颜色

脚本编写

工具 说明
create_script(name, template?, code?) 创建JavaScript脚本资源
attach_script(object, script) 将脚本附加到场景对象
create_tap_trigger(object, script) 点击对象时运行代码
create_state_machine(states, transitions, initial) 创建状态机
generate_script_from_description(description) AI从自然语言生成脚本

音频

工具 说明
add_audio(name, loop?, volume?) 添加音频组件
play_sound_on_trigger(sound, trigger) 播放点击声音、微笑等。
apply_voice_effect(effect) 向上/向下倾斜、回声、机器人、耳语
sync_to_music_beat(object, property?, intensity?) 与音乐同步制作动画
search_music_library(query) 搜索授权音乐
install_licensed_music(track_id) 从库中安装曲目

后处理

工具 说明
add_post_effect(type, intensity?) 开花、模糊、渐晕、色差、纹理、锐化
apply_color_grading(preset, intensity?) 温暖、凉爽、复古、赛博朋克、柔和、高对比度
create_custom_lut(name) 导入自定义颜色LUT
add_screen_effect(effect, blend_mode?) 漏光、镜头光斑覆盖

镜片配方

工具 说明
list_lens_recipes() 列出可用的配方模板
create_lens_from_recipe(recipe) 从模板构建一个完整的镜头
create_face_filter_lens(features) 从特征列表创建面部过滤器
create_try_on_lens(asset_type) 眼镜、帽子、耳环等的虚拟试穿。
create_game_lens(game_type) 交互式AR游戏（捕捉、点击、手势测验）

3D模型库（Sketchfab）

工具 说明
search_3d_models(query) 在Sketchfab中搜索可下载的3D模型
import_3d_model(uid) 下载模型并将其导入Lens Studio

macOS UI自动化（回退）

对于无法通过API进行的操作： ui_activate, ui_menu_click, ui_new_project, ui_save_project, ui_open_project, ui_preview, ui_keystroke, ui_type_text, ui_import_asset, ui_export_lens, ui_add_object, ui_dump_menus, ui_list_buttons, ui_click_button, ui_request_permissions

环境变量

变量 默认值 描述
LENS_MCP_PORT 50050 Lens Studio的MCP服务器端口
LENS_MCP_TOKEN_FILE ~/.lens_mcp_token.json 缓存身份验证令牌的路径
SKETCHFAB_API_TOKEN （无） 用于三维模型搜索/导入的Sketchfab API令牌
SKETCHFAB_BASE_URL https://api.sketchfab.com/v3 Sketchfab API基础URL
LENS_MCP_MODEL_CACHE ~/.cache/lens-mcp/models/ 下载的3D模型的缓存目录

故障排除

问题 解决方案
“连接被拒绝” 确保Lens Studio 5.15+已打开并加载了项目
“401 Unauthorized” 镜头工作室已重新启动--删除 ~/.lens_mcp_token.json 并重新连接
权限弹出窗口未出现 检查Lens Studio是否位于前台且未被对话框遮挡
UI自动化工具失败 仅限macOS--运行 ui_request_permissions 授予无障碍访问权限
Sketchfab工具返回错误 设置 SKETCHFAB_API_TOKEN 在MCP配置中 env 挡块

运行测试

source .venv/bin/activate
python -m pytest smoke_test.py -v

所有160个测试都在模拟Lens Studio服务器上运行，不需要真正的Lens Studio实例。

安全

  • Lens Studio的MCP服务器绑定到 localhost 仅--无法从网络访问
  • 身份验证令牌存储在本地 ~/.lens_mcp_token.json
  • SSE/HTTP传输绑定到 127.0.0.1 默认情况下
  • Sketchfab API令牌是从环境变量中读取的，从不硬编码

许可证

麻省理工学院

相关 MCP