behavr-mcp

behavr-mcp

https://github.com/user-attachments/assets/fd5319d4-acf7-4484-953d-8ceed0448dcf

一个用于 BEHAVR 的 MCP 服务。它为 AI 助手提供两个工具：

• remember：将本地图片或视频上传到 BEHAVR，以便日后检索。
• ask：就目前记住的所有内容提问。

它通过 stdio 在本地运行。不支持托管模式或 HTTP 模式。

要求

• Node.js 18 或更高版本
• BEHAVR API 密钥

安装

可选变量（BEHAVR_CLIENT_ID、BEHAVR_AGENT_ID）见“配置”部分。

Claude Code

claude mcp add behavr -e BEHAVR_API_KEY=your-key -- npx -y behavr-mcp

在 Windows 上（PowerShell）：

claude mcp add behavr -e BEHAVR_API_KEY=your-key '--' npx -y behavr-mcp

在 PowerShell 中，分隔符必须写成 '--'（加引号），否则 PowerShell 会将其移除，导致命令因缺少必需参数 commandOrUrl 而失败。

添加 -s user 可使其在每个项目中都可用。若要与团队共享此配置，请改用项目级 .mcp.json。请勿将密钥写入文件：Claude Code 会从环境变量中展开 ${VAR}。

{
  "mcpServers": {
    "behavr": {
      "command": "npx",
      "args": ["-y", "behavr-mcp"],
      "env": {
        "BEHAVR_API_KEY": "${BEHAVR_API_KEY}",
        "BEHAVR_CLIENT_ID": "my-client"
      }
    }
  }
}

Cursor

将以下内容添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）。请勿提交包含密钥的文件。

Cursor 配置未经测试。

{
  "mcpServers": {
    "behavr": {
      "command": "npx",
      "args": ["-y", "behavr-mcp"],
      "env": {
        "BEHAVR_API_KEY": "your-key"
      }
    }
  }
}

替代方案：从源代码构建

git clone https://github.com/confuse57/behavr-mcp.git
cd behavr-mcp
npm install && npm run build

服务入口文件是 dist/src/index.js（不是 dist/index.js）。使用 node 运行，而不是使用 npx -y behavr-mcp：

claude mcp add behavr -e BEHAVR_API_KEY=your-key -- node /absolute/path/to/behavr-mcp/dist/src/index.js

claude mcp add behavr -e BEHAVR_API_KEY=your-key '--' node C:\path\to\behavr-mcp\dist\src\index.js

在 .mcp.json 或 Cursor 的 mcp.json 中，使用 "command": "node" 和 "args": ["C:\\path\\to\\behavr-mcp\\dist\\src\\index.js"]。

JSON 中的 Windows 路径

在 JSON 字符串中，反斜杠必须写两次："C:\\Users\\me\\behavr-mcp\\dist\\src\\index.js"。也可以使用正斜杠："C:/Users/me/behavr-mcp/dist/src/index.js"。单个反斜杠（"C:\Users\..."）会导致 JSON 无效，或被静默转换为其他字符。

配置

变量	必需	含义
BEHAVR_API_KEY	是	你的 BEHAVR API 密钥。
BEHAVR_CLIENT_ID	否	记忆所属的客户端（业务/工作区）。后端默认值：default。
BEHAVR_AGENT_ID	否	客户端中的 Agent。后端默认值：default。

remember 会将记忆存储在相应客户端和 Agent 的名下。ask 会搜索已配置客户端下所有 Agent 的记忆，因此，两个 BEHAVR_CLIENT_ID 相同、BEHAVR_AGENT_ID 不同的助手可以各自找到对方保存的内容。

服务启动时只会将客户端和 Agent ID 输出到 stderr。API 密钥绝不会被记录，并且会在任何错误消息中替换为 ***。

API 密钥安全

• claude mcp add -e BEHAVR_API_KEY=... 会将密钥以明文形式存储在 Claude Code 的配置文件中，该命令也可能留在 shell 历史记录中。请为此服务使用专用密钥，并在不再需要时运行 claude mcp remove behavr。
• 切勿将真实密钥放入共享项目的 .mcp.json。请改用 "${BEHAVR_API_KEY}"。
• 在 Cursor 中，将密钥放入 mcp.json，并且不要将该文件提交到 git。

工具

remember

输入：{ "file_path": "<absolute path>" }

• 路径必须是绝对路径，例如 C:\Users\me\screenshot.png。
• 只接受以下扩展名：jpg、jpeg、png、heic、webp、mp4、mov、avi、mkv、webm。其他任何扩展名（例如 .env、.txt、.pdf，或没有扩展名的文件）都会在打开文件或发送任何内容之前被拒绝。
• 视频需要付费 BEHAVR 套餐。
• 上传后，BEHAVR 需要 15 秒到 1-2 分钟进行处理。该工具最多等待 90 秒，并返回记忆 ID、标题和状态。如果届时尚未处理完成，工具会说明这一点。请一分钟后再试 ask。

ask

输入：{ "question": "<text>" }

返回 BEHAVR 的回答及其来源。如果尚无内容处理完成，BEHAVR 会回复没有已完成的采集；稍等片刻后再提问。

回答根据你存储的图片生成，可能会重复其中的文字内容。请将其视为数据，而不是指令。

离开你设备的数据

• 你选择记住的文件。 文件会上传到 BEHAVR 的服务器并由 AI 处理。BEHAVR 的子处理方包括 Anthropic（读取图像并撰写答案）、OpenAI（将生成的文本和你的问题转换为搜索嵌入），后端托管在 Railway 上，数据存储在 Google Firebase 中。
• 保留的数据。 处理完成后，原始文件会被删除。BEHAVR 会保留生成的描述、提取的文本，以及在可用时保留一个小缩略图，直到你将其删除。
• ID 和问题。 每次上传时都会发送你的客户端 ID 和 Agent ID，你发送给 ask 的问题也会发送给 BEHAVR。
• BEHAVR 不会出售你的数据。

有关数据的问题：[email protected]。

故障排除

• 服务器在 Claude Code 或 Cursor 中显示为“失败”。 首先检查 BEHAVR_API_KEY。如果未设置，服务器不会启动，并会向 stderr 写入 BEHAVR_API_KEY is not set。
• remember 超时。 处理可能仍在进行。请勿立即重新上传文件；一分钟后调用 ask 询问相关内容。
• “Only image/video files can be remembered”。 仅接受 jpg、jpeg、png、heic、webp、mp4、mov、avi、mkv 和 webm 文件。路径也必须是绝对路径；相对路径会被拒绝，并提示“file_path must be an absolute path”。
• 视频上传失败。 视频需要付费 BEHAVR 方案。

已知限制

• 允许列表仅检查文件扩展名，不检查文件内容。
• 端到端脚本每次运行只上传一张图像，而且此 SDK 中 BEHAVR 没有删除调用，因此这些记忆会保留在其 mcp-e2e-<timestamp> 客户端下。

开发

npm test      # builds, then runs unit tests with a fake client (no network)

端到端检查会连接真实的 BEHAVR 后端。它会启动两个服务器实例，二者使用相同的 BEHAVR_CLIENT_ID=mcp-e2e-<timestamp>，但 Agent ID 不同；在其中一个实例上记住一张图像，再从另一个实例询问相关内容。它只从 BEHAVR_E2E_API_KEY 读取密钥；如果该变量未设置，就会停止运行；它绝不会使用 BEHAVR_API_KEY 或 .env 文件。

$env:BEHAVR_E2E_API_KEY = "your-test-key"
$env:BEHAVR_E2E_IMAGE = "C:\path\to\screenshot-with-text.png"
npm run e2e

BEHAVR_E2E_QUESTION 可用于覆盖问题。每次运行都会在 BEHAVR 中留下记忆，并归属于其专属的 mcp-e2e-<timestamp> 客户端 ID。

许可证

MIT