Elabftw MCP Server

labFTW MCP服务器

一种用于交互的模型上下文协议（MCP）服务器 手工 -一个开源的电子实验室笔记本。

该服务器允许像Claude（通过Claude Desktop）或本地LLM（通过Ollama）这样的AI助手在您的labFTW实例中读写实验和数据库项（资源）。

特性

实验

• 列出实验：使用分页、搜索和所有者筛选浏览实验
• 获取实验详细信息：检索完整的实验数据，包括正文、标签和元数据
• 创建实验：使用标题、正文（支持HTML）、模板、类别和标签创建新的实验
• 更新实验：修改现有实验（标题、正文、类别、状态）
• 删除实验：软删除实验
• 标签管理：在实验中添加和删除标签
• 链接项目：将实验链接到其他实验或数据库项
• 上传附件：将文件附加到实验中
• 列出模板和类别：发现可用的实验模板和类别

数据库项（资源）

• 列出项目：通过搜索、类别和所有者筛选浏览资源（化学品、设备、设置等）
• 获取物品详情：检索完整的项目数据，包括正文、标签和链接的项目
• 创建项目：将新资源添加到您的实验室清单中
• 更新项目：修改现有项目（标题、正文、类别、评级）
• 删除项目：软删除项目
• 标签管理：在项目中添加和删除标签
• 上传附件：将文件（数据表、手册、证书）附加到项目上
• 链接项目：将项目连接到其他项目或实验
• 列出项目类型：发现可用的项目类别（化学品、设备、设置等）

先决条件

• Python 3.10或更高版本
• 一个labFTW服务器实例
• 来自elabTW帐户的API密钥

安装

1.克隆或下载

git clone 
cd elabftw-mcp

2.创建虚拟环境

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3.安装依赖项

pip install -r requirements.txt

4.配置环境

复制示例环境文件并填写您的凭据：

cp .env.example .env

编辑 .env 使用您的设置：

ELABFTW_API_URL=https://your-elabftw-server/api/v2
ELABFTW_API_KEY=your-api-key-here
ELABFTW_VERIFY_SSL=false

获取API密钥

1. 登录到您的labFTW实例
2. 点击用户菜单（右上角）
3. 首选 用户面板 → API密钥
4. 创建具有适当权限的新API密钥
5. 立即复制密钥（不会再次显示）

用法

使用克劳德桌面

将服务器添加到Claude Desktop配置文件中：

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

{
  "mcpServers": {
    "elabftw": {
      "command": "python",
      "args": ["/absolute/path/to/elabftw_mcp_server.py"],
      "env": {
        "ELABFTW_API_URL": "https://your-elabftw-server/api/v2",
        "ELABFTW_API_KEY": "your-api-key-here",
        "ELABFTW_VERIFY_SSL": "false"
      }
    }
  }
}

更改后重新启动Claude Desktop。

与Ollama（通过mcp桥或类似方式）

对于Ollama集成，您可以使用以下工具 mcp桥 或类似于OpenAI适配器的MCP：

# Start the MCP server
export ELABFTW_API_URL="https://your-elabftw-server/api/v2"
export ELABFTW_API_KEY="your-api-key-here"
export ELABFTW_VERIFY_SSL="false"

python elabftw_mcp_server.py

独立测试

您可以直接使用MCP检查器测试服务器：

npx @modelcontextprotocol/inspector python elabftw_mcp_server.py

可用工具

实验工具

list_experiments

列出您的labFTW实例中的实验。

参数：

• limit （可选，int）：要返回的最大实验数（默认值：15，最大值：100）
• offset （可选，int）：分页时要跳过的实验数
• search （可选，字符串）：搜索查询以过滤实验
• owner （可选，字符串）：按所有者用户ID筛选。可以是单个ID，如“2”，也可以是逗号分隔的，如“2,3”

示例提示：

• “列出我最近的实验”
• “搜索有关PCR的实验”
• “显示用户5创建的实验”
• “列出用户3和7的实验”

get_experiment

获取特定实验的详细信息。

参数：

• experiment_id （必填，int）：实验的唯一ID

示例提示： “给我看看实验42的细节”

create_experiment

创建一个新的实验。

参数：

• title （必填，字符串）：实验标题
• body （可选，字符串）：实验内容/正文（支持HTML）
• template （可选，int）：初始结构的模板ID（-1表示空，0表示团队默认值）
• category （可选，int）：分类的类别ID
• tags （可选，字符串数组）：要添加的标签

示例提示： “创建一个名为‘蛋白质’和‘分析’标签的‘蛋白质印迹分析’新实验”

update_experiment

更新现有实验。

参数：

• experiment_id （必填，int）：要更新的实验ID
• title （可选，字符串）：新标题
• body （可选，字符串）：新正文/内容
• category （可选，int）：新类别ID
• status （可选，int）：新状态ID

示例提示： “用新结果部分更新实验42”

delete_experiment

删除实验（软删除）。

参数：

• experiment_id （必填，int）：要删除的实验ID

add_tag

在实验中添加标签。

参数：

• experiment_id （必填，int）：实验ID
• tag （必填，字符串）：要添加的标记

remove_tag

从实验中删除标签。

参数：

• experiment_id （必填，int）：实验ID
• tag_id （必填，int）：要删除的标记ID

set_experiment_status

设置实验的状态。

参数：

• experiment_id （必填，int）：实验ID
• status_id （必填，int）：要设置的状态ID

link_item

将实验或数据库项链接到实验。

参数：

• experiment_id （必填，int）：要链接到的实验
• link_id （必填，int）：要链接的项目/实验的ID
• link_type （可选，字符串）：“实验”或“项目”（默认为“实验”）

upload_attachment

将文件上传到实验中。

参数：

• experiment_id （必填，int）：实验ID
• file_path （必填，字符串）：文件路径
• comment （可选，字符串）：附件注释

list_experiment_templates

列出可用的实验模板。

参数：

• limit （可选，int）：要返回的最大模板数
• offset （可选，int）：分页偏移量

list_experiment_categories

列出可用的实验类别。

参数：

• team_id （可选，int）：团队ID（默认值：1）

______________________________________________________________________

数据库项（资源）工具

list_items

列出数据库项目（资源），如化学品、设备、设置等。

参数：

• limit （可选，int）：要返回的最大项目数（默认值：15，最大值：100）
• offset （可选，int）：分页时要跳过的项目数
• search （可选，字符串）：搜索查询以筛选项目
• category （可选，int）：要筛选的类别/类型ID
• owner （可选，字符串）：按所有者用户ID筛选。可以是单个ID，如“2”，也可以是逗号分隔的，如“2,3”

示例提示：

• “列出数据库中的所有化学品”
• “搜索含有‘钠’的项目”
• “显示用户4拥有的设备”
• “列出用户2或5创建的资源”

get_item

获取特定数据库项的详细信息。

参数：

• item_id （必填，int）：项目的唯一ID

示例提示： “显示项目15的详细信息”或“获取有关NaCl条目的信息”

create_item

创建新的数据库项（资源）。

参数：

• category （必填，int）：类别/类型ID（使用 list_items_types 查找有效ID）
• title （可选，字符串）：项目的标题（例如，化学名称、设备名称）
• body （可选，字符串）：内容（支持HTML）-规范、注释、安全信息
• tags （可选，字符串数组）：要添加的标签

示例提示：

• “创建氯化钠的新化学条目”
• “为离心机添加新设备项”
• “为PCR工作站创建设置条目”

update_item

更新现有数据库项。

参数：

• item_id （必填，int）：要更新的项目的ID
• title （可选，字符串）：新标题
• body （可选，字符串）：新正文/内容
• category （可选，int）：新类别/类型ID
• rating （可选，int）：评级0-5（适用于质量/可靠性评级）

示例提示： “用新的安全信息更新项目15”

delete_item

删除数据库项（软删除）。

参数：

• item_id （必填，int）：要删除的项目ID

list_items_types

列出可用的项目类型/类别（例如，化学品、设备、质粒、设置）。

参数：

• team_id （可选，int）：团队ID（默认值：1）

示例提示： “我可以在数据库中存储哪些类型的项目？”

add_item_tag

向数据库项添加标记。

参数：

• item_id （必填，int）：项目ID
• tag （必填，字符串）：要添加的标记

remove_item_tag

从数据库项中删除标记。

参数：

• item_id （必填，int）：项目ID
• tag_id （必填，int）：要删除的标记ID

upload_item_attachment

将文件上传到数据库项（数据表、手册、证书等）。

参数：

• item_id （必填，int）：项目ID
• file_path （必填，字符串）：文件路径
• comment （可选，字符串）：附件注释

示例提示： “将安全数据表上传到NaCl项目”

link_to_item

将另一个项目或实验链接到数据库项目。

参数：

• item_id （必填，int）：要链接到的项目
• link_id （必填，int）：要链接的项目/实验的ID
• link_type （可选，字符串）：“items”或“experiments”（默认值：“item”）

示例提示： “将离心机设备与本协议联系起来”

示例工作流

管理实验室库存

You: "What types of items can I store in the database?"
AI: [calls list_items_types] "You can store: Chemicals, Equipment, Plasmids, Cell Lines, Setups..."

You: "Create a new chemical entry for DMSO with purity 99.9%"
AI: [calls create_item] "Created DMSO entry with ID 123"

You: "Add a tag 'solvent' to that chemical"
AI: [calls add_item_tag] "Tag 'solvent' added to item 123"

按所有者筛选

You: "Show me all experiments created by user 5"
AI: [calls list_experiments with owner="5"] "Found 12 experiments by user 5..."

You: "List chemicals added by users 3 or 7"
AI: [calls list_items with owner="3,7"] "Found 8 items created by users 3 and 7..."

You: "Show experiments from Sarah"
AI: "I'll need the user ID. Let me list users first..." [determines user ID] "Found Sarah is user 5" [calls list_experiments with owner="5"]

将资源与实验联系起来

You: "Show me my recent experiments"
AI: [calls list_experiments] "Here are your experiments..."

You: "Link the DMSO chemical (item 123) to experiment 45"
AI: [calls link_item] "Successfully linked item 123 to experiment 45"

查找设备和设置

You: "Search for all setups related to PCR"
AI: [calls list_items with search="PCR"] "Found 3 PCR-related setups..."

You: "Get details on setup 78"
AI: [calls get_item] "Setup 78: PCR Workstation - includes thermal cycler, pipettes..."

SSL证书问题

如果您的labFTW服务器使用自签名证书（在实验室设置中很常见），请设置：

ELABFTW_VERIFY_SSL=false

对于具有有效SSL证书的生产环境，请将其设置为 true.

故障排除

“连接被拒绝”错误

• 验证服务器URL是否正确
• 检查服务器是否可以从您的计算机访问
• 确保防火墙规则允许连接

“401未经授权”错误

• 验证您的API密钥是否正确
• 检查API密钥是否具有必要的权限
• 确保API密钥未过期

“SSL证书错误”

• 集 ELABFTW_VERIFY_SSL=false 用于自签名证书
• 或者在您的系统上安装服务器的CA证书

服务器未出现在Claude Desktop中

• 验证Python脚本的路径是否为绝对路径
• 检查Claude Desktop日志是否有错误
• 确保Python在PATH中或使用Python可执行文件的完整路径

创建项目时出现“需要类别ID”错误

• 数据库项需要一个类别/类型。使用 list_items_types 首先找到有效的类别ID

安全注意事项

• 永远不要承诺你的 .env 文件 或版本控制的API密钥
• 对API密钥使用环境变量或安全秘密管理
• 在生产中，始终使用 ELABFTW_VERIFY_SSL=true 持有有效证书
• API密钥应具有最低限度的必要权限

贡献

欢迎投稿！请随时提交问题或拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

致谢

• 手工 -优秀的开源电子实验室笔记本
• 模型上下文协议 -实现AI工具集成的协议