AI导哈

家庭物品查询服务器

一个连接Homebox家庭物品清单系统的模型上下文协议（MCP）服务器，允许AI助手实时查询和探索您的家庭物品清单数据。

  • by jeeves5454
  • JavaScript
  • 本地部署
  • 10 星标
  • 更新于
在 GitHub 查看 jeeves5454/Homebox-mcp

使用说明

Homebox MCP服务器

一个模型上下文协议（MCP）服务器，连接到您的Homebox家庭库存系统，允许AI助手实时查询和探索您的家庭库存数据。

这是什么？

此MCP服务器充当AI助手（如Claude）和Homebox家庭库存数据库之间的桥梁。它允许您的AI助手：

  • 在您的库存中搜索商品
  • 获取特定项目的详细信息
  • 列出您存放物品的所有位置
  • 列出您使用的所有标签/类别
  • 查找特定位置的所有项目
  • 查找具有特定标签的所有项目

部署选项

选择最适合您用例的集成方法：

适用于开放式WebUI+Ollama用户

适用于Claude桌面用户（MCP协议）

我应该选择哪一个？

先决条件（本地安装）

注： 如果您使用的是Docker/RDL，请参阅 医生.md 相反。

在开始之前，您需要：

  1. Node.js -版本18或更高(点击此处下载)
  2. 正在运行的Homebox实例 -您应该已经安装了Homebox并且可以访问
  3. Homebox登录凭据 -您的Homebox电子邮件和密码

分步安装说明（本地安装）

第一步：安装Node.js

  1. 首选 nodejs.org
  2. 下载LTS（长期支持）版本
  3. 运行安装程序并按照提示操作
  4. 打开终端/命令提示符并验证安装：
    node --version
npm --version
    这两个命令都应该显示版本号。

步骤2：下载此MCP服务器

如果你还没有：

git clone <your-repository-url>
cd Homebox-mcp

步骤3：安装依赖项

在 Homebox-mcp 文件夹，运行：

npm install

这将下载所有必需的库。

步骤4：配置您的Homebox连接

  1. 复制示例配置文件：

    cp config.json.example config.json

  2. 打开 config.json 在文本编辑器中填写您的详细信息：

    {
  "homeboxUrl": "http://localhost:7745",
  "email": "your-email@example.com",
  "password": "your-password"
}

    替换：

    • homeboxUrl：运行Homebox的URL（默认为 http://localhost:7745)
    • email：您的Homebox登录电子邮件
    • password：您的Homebox登录密码

  3. 保存文件

步骤5：构建服务器

编译TypeScript代码：

npm run build

步骤6：测试连接

在运行完整服务器之前，测试它是否可以连接到Homebox：

npm test

这将验证您的配置，并显示是否一切正常。如果成功，您将看到绿色复选标记和库存摘要。

或者，您可以测试整个服务器：

npm start

如果成功，您应该看到：

Starting Homebox MCP Server...
Successfully authenticated with Homebox
Homebox MCP Server running on stdio

按 Ctrl+C 停止服务器。您已准备好配置您的AI助手！

使用Claude Desktop进行配置

要将此MCP服务器与Claude Desktop一起使用：

  1. 打开您的Claude Desktop配置文件：

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

  2. 将Homebox MCP服务器添加到配置中：

    {
  "mcpServers": {
    "homebox": {
      "command": "node",
      "args": ["/absolute/path/to/Homebox-mcp/dist/index.js"]
    }
  }
}

    替换 /absolute/path/to/Homebox-mcp 带有Homebox mcp文件夹的实际完整路径。

    macOS/Linux示例：

    {
  "mcpServers": {
    "homebox": {
      "command": "node",
      "args": ["/home/username/Homebox-mcp/dist/index.js"]
    }
  }
}

    Windows示例：

    {
  "mcpServers": {
    "homebox": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\Homebox-mcp\\dist\\index.js"]
    }
  }
}

  3. 保存文件并重新启动Claude Desktop

使用MCP服务器

配置后，您可以让Claude与您的Homebox库存进行交互。以下是一些示例查询：

搜索项目

“你能在我的Homebox库存中搜索‘螺丝刀’吗？”

列出所有地点

“显示我的Homebox库存中的所有位置”

在某个位置查找项目

“车库里有什么物品？”（首先使用list_location获取位置ID，然后使用get_items_by_location）

列出所有标签

“我在Homebox中使用哪些标签/类别？”

获取项目详细信息

“您能获取项目ID 123的完整详细信息吗？”

按标签查找项目

“显示所有标记为“电子产品”的项目”

有关更详细的示例和用例，请参阅 示例.md.

可用工具

MCP服务器提供以下工具：

  1. 搜索项目 -按名称或描述搜索项目
  2. 获取项目 -获取特定项目的完整详细信息
  3. list_location -列出所有存储位置
  4. get_location -获取特定位置的详细信息
  5. list_labels -列出所有标签/类别
  6. get_label -获取特定标签的详细信息
  7. get_items_by_location -获取某个位置的所有项目
  8. get_items_by_label -获取带有标签的所有项目

故障排除

“身份验证失败”

  • 检查你的 config.json 有正确的电子邮件和密码
  • 验证您的Homebox实例是否正在运行
  • 确保 homeboxUrl 是正确的

“找不到模块”

  • 跑 npm install 再次
  • 确保你跑了 npm run build

“ECONNREFUSED”或“网络错误”

  • 检查Homebox是否正在运行
  • 验证中的URL config.json 是正确的
  • 如果使用Docker，请确保Homebox容器正在运行

Claude Desktop未显示工具

  • 检查路径是否正确 claude_desktop_config.json 是绝对的（完整路径）
  • 更改配置后重新启动Claude Desktop
  • 检查Claude Desktop日志是否有错误

安全说明

  • 你的 config.json 文件包含您的Homebox密码-请确保其安全
  • 这 .gitignore 文件已配置为防止 config.json 从致力于git
  • 永远不要分享你的 config.json 公开文件

运作原理

MCP服务器方法（克劳德桌面）

此MCP服务器：

  1. 通过其REST API连接到Homebox实例
  2. 使用您的凭据进行身份验证
  3. 提供Claude可用于查询您的库存的工具
  4. 以Claude可以理解并呈现给您的格式返回数据

服务器不直接访问SQLite数据库。相反，它使用Homebox的官方API，这对于实时访问来说更安全、更可靠。

开放式WebUI函数方法（Ollama）

Open WebUI集成：

  1. 在Open WebUI中作为本机函数安装
  2. 直接从Open WebUI中调用Homebox REST API
  3. 适用于任何可调用函数的Olama模型（Llama 3.1、Mistral、Qwen等）
  4. 不需要单独的服务器进程
  5. 非常适合在ExpressRoute上部署Docker

看 OPEN-WEBUI.md 有关完整的设置说明。

发展

如果要修改服务器：

  1. 编辑文件 src/ 目录
  2. 重建与 npm run build
  3. 重新启动服务器

许可证

麻省理工学院

支持

如果您遇到问题：

  1. 检查上面的故障排除部分
  2. 验证您的Homebox实例是否正常工作
  3. 请查看Homebox文档，网址为 homebox软件

相关 MCP