Karakeep (Hoarder) MCP 服务器

该项目提供了一个与 Mind Control Panel (MCP) 兼容的服务器，允许通过其 API 与 Karakeep 书签服务进行交互（搜索和创建书签）。

它被设计为供大型语言模型（LLMs）或其他能够根据由 Glama.ai 等服务定义的 MCP 协议发出 HTTP 请求的客户端使用。

功能

• 搜索书签： 根据查询字符串在 Karakeep 中查找现有书签。
• 创建书签： 使用 URL 和可选标题/描述向 Karakeep 添加新书签。
• MCP 兼容端点： 暴露一个 /mcp 端点用于操作。
• 环境变量配置： 安全地配置您的 Hoarder API 密钥。

前提条件

• Python 3.8+
• 一个 Karakeep 账户和 API 密钥 (参见 Karakeep API 文档)
• 访问托管平台（例如 Render、Heroku、Fly.io、VPS）或 Docker 进行部署。

设置和本地开发

1. 克隆仓库：

   git clone <your-repository-url>
   cd hoarder-mcp-server
   

2. 创建虚拟环境（推荐）：

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上使用 `venv\Scripts\activate`
   

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 配置环境变量：

   • 在项目根目录中创建一个名为 .env 的文件。
   • 将您的 Hoarder API 密钥添加到其中：

     HOARDER_API_KEY="YOUR_HOARDER_API_KEY_HERE"
     

   • 重要提示： 确保 .env 文件被列入 .gitignore 文件中，以避免提交敏感信息。

5. 本地运行服务器：

   uvicorn main:app --reload --port 8000
   

   服务器将在 http://127.0.0.1:8000 可用。--reload 标志会在检测到代码更改时自动重启服务器。

API 使用

服务器暴露了一个单独的 POST 端点：/mcp。

请求体（JSON）：

{
  "action": "action_name",
  "parameters": {
    "param1": "value1",
    "param2": "value2"
    // ... action-specific parameters
  }
}