项目简介

InstrMCP是一个强大的MCP服务器，旨在连接大语言模型（LLM）与物理实验室的仪器和数据。它通过标准化协议，让LLM能够查询仪器状态、读取测量数据、生成实验代码，甚至在用户授权下执行自动化操作。这大大提高了实验室工作的智能化和效率。

主要功能点

全面QCodes集成: 内置支持所有QCodes仪器驱动，允许LLM获取仪器信息、参数值、站台快照等。
动态工具创建: 支持LLM在运行时注册、更新和撤销自定义MCP工具，实现高度灵活的功能扩展。
JupyterLab深度集成: 提供对Jupyter笔记本的变量、单元格内容、输出的读写访问能力，并支持移动光标、添加/删除/修改单元格（在非安全模式下）。
QCodes数据库访问: 提供对QCodes数据库的只读访问，包括列出实验、获取数据集信息、查询数据库统计数据等。
MeasureIt模板库: 提供全面的MeasureIt测量模式库和代码生成模板，帮助LLM快速生成各种复杂测量的代码。
安全模式与授权机制: 默认运行在安全模式，限制LLM执行修改操作；非安全模式下，所有可能修改环境的操作（如执行代码、删除单元格）都需用户通过对话框进行视觉确认和授权。
多LLM客户端兼容: 经测试可与Claude Desktop、Claude Code和Codex CLI等客户端无缝集成。

安装步骤

克隆仓库:

git clone https://github.com/caidish/instrMCP.git
cd instrMCP

安装Python包:
```
pip install -e .
```

设置环境变量 (可选但推荐):

macOS/Linux:

export instrMCP_PATH="$(pwd)"
echo 'export instrMCP_PATH="'$(pwd)'"' >> ~/.zshrc  # 或 ~/.bashrc
source ~/.zshrc

Windows (PowerShell):

$env:instrMCP_PATH = (Get-Location).Path
[System.Environment]::SetEnvironmentVariable('instrMCP_PATH', (Get-Location).Path, 'User')

安装JupyterLab扩展 (非必需，但推荐在JupyterLab中使用时安装，确保JupyterLab >= 4.x):

jupyter labextension develop instrmcp/extensions/jupyterlab/mcp_active_cell_bridge --overwrite
jupyter lab build

服务器配置 (MCP客户端用于连接InstrMCP服务器)

InstrMCP服务器在Jupyter环境中通过魔法命令启动时，默认在'http://127.0.0.1:8123'监听。如果通过CLI启动QCodes Station服务器，则默认监听'http://127.0.0.1:3001'。以下是几种典型MCP客户端的配置示例，以JSON格式提供关键连接信息：

连接到Jupyter模式下的InstrMCP服务器 (推荐，提供最完整功能):

{
    "serverName": "JupyterInstrMCP",
    "command": "python",
    "args": [
        "/path/to/your/instrMCP/claudedesktopsetting/claude_launcher.py"
    ],
    "env": {
        "JUPYTER_MCP_HOST": "127.0.0.1",
        "JUPYTER_MCP_PORT": "8123",
        "instrMCP_PATH": "/path/to/your/instrMCP"
    },
    "description": "通过JupyterLab环境与物理仪器交互的MCP服务器，支持动态工具和笔记本控制。"
}

请注意:

将'/path/to/your/instrMCP'替换为InstrMCP仓库的实际路径。
在启动MCP客户端之前，确保您已在Jupyter Notebook或JupyterLab中加载并启动了InstrMCP扩展：
- 启动JupyterLab: 'jupyter lab'
- 在Notebook单元格中运行: '%load_ext instrmcp.extensions'
- 启动MCP服务器: '%mcp_start'
- (可选) 切换到不安全模式: '%mcp_unsafe'
- (可选) 启用数据库和MeasureIt选项: '%mcp_option add database measureit'
此配置使用'claude_launcher.py'作为STDIO代理，将MCP客户端的STDIO请求转发到Jupyter模式下运行的HTTP MCP服务器。

连接到独立的QCodes Station服务器 (提供基本的QCodes仪器访问):

{
    "serverName": "QCodesStationMCP",
    "command": "instrmcp",
    "args": [
        "qcodes",
        "--port",
        "3001"
    ],
    "description": "提供对QCodes站台仪器健康状态和控制的独立MCP服务器。"
}

请注意:

此配置直接启动一个独立的QCodes Station服务器，无需JupyterLab。
如果'instrmcp'命令不在系统PATH中，您可能需要提供其完整路径，例如'/path/to/your/instrMCP/venv/bin/instrmcp'。

基本使用方法

在JupyterLab中启动InstrMCP服务器:

打开JupyterLab (确保已安装JupyterLab扩展): 'jupyter lab'

在任意Notebook单元格中运行以下命令:

%load_ext instrmcp.extensions  # 加载InstrMCP IPython扩展
%mcp_start                   # 启动MCP服务器 (默认安全模式，监听127.0.0.1:8123)
%mcp_status                  # 查看服务器状态
# 如果需要LLM执行代码或修改Notebook，切换到不安全模式（需重启服务器）
# %mcp_unsafe
# %mcp_restart
# 启用可选功能，如数据库和MeasureIt（需重启服务器）
# %mcp_option add database measureit
# %mcp_restart

通过LLM客户端交互:
- 配置您的LLM客户端（如Claude Desktop, Claude Code, Codex CLI）以连接到InstrMCP服务器，参考上述“服务器配置”部分。
- 在LLM客户端中，您可以：
  - 查询可用MCP工具: "What MCP tools are available?" (调用'mcp_list_resources'工具)
  - 获取QCodes仪器信息: "Show me the info for 'my_instrument' with values." (调用'qcodes_instrument_info'工具)
  - 读取当前编辑单元格内容: "Get the content of the currently editing cell." (调用'notebook_get_editing_cell'工具)
  - （在不安全模式下）请求LLM修改当前单元格内容或执行代码，例如：“Change 'x=10' to 'x=20' in the current cell.” (调用'notebook_apply_patch'工具) 或 “Execute the current cell.” (调用'notebook_execute_cell'工具)。
  - （在不安全模式下）请求LLM动态注册一个新工具: "Register a new tool named 'calculate_avg' that takes an array of numbers and returns their average." (调用'dynamic_register_tool'元工具)

关键词

项目简介

主要功能点

安装步骤

服务器配置 (MCP客户端用于连接InstrMCP服务器)

基本使用方法

信息