Kibela MCP Server

概述

Kibela MCP 服务目前仅支持通过 STDIO 运行的本地服务，可与 Claude Desktop 或 VSCode 等任何 MCP 客户端搭配使用。

此处仅将公开可用且适合 MCP 的 GraphQL API 实现为工具。

使用场景

• 查询 Kibela 中的信息
• 整理 Kibela 中的文件夹和文章
• 借助 AI 使用 Kibela 辅助写作

要求

1. 已安装 Docker
2. Docker 必须处于运行状态
3. 已签发 Kibela 访问令牌
4. 已安装实现了 MCP 客户端 的应用程序

安装

示例：Claude Desktop

将以下配置写入 claude_desktop_config.json。将 Kibela 来源地址和访问令牌设置为环境变量。

{
  "mcpServers": {
    "kibela": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-e",
        "KIBELA_ORIGIN",
        "-e",
        "KIBELA_ACCESS_TOKEN",
        "ghcr.io/kibela/kibela-mcp-server"
      ],
      "env": {
        "KIBELA_ORIGIN": "https://your-subdomain.kibe.la",
        "KIBELA_ACCESS_TOKEN": "***"
      }
    }
  }
}

不使用 Docker

然后将脚本设置为执行命令。此时，请确保脚本路径为绝对路径。

{
  "mcpServers": {
    "kibela": {
      "command": "/path/to/kibela-mcp-server/bin/cli.mjs",
      "env": {
        "KIBELA_ORIGIN": "https://your-subdomain.kibe.la",
        "KIBELA_ACCESS_TOKEN": "***"
      }
    }
  }
}

可用工具

笔记操作

• search_kibela_note - 搜索笔记

  • query：搜索关键词（必填）
  • resources：资源类型筛选条件（可选）
  • coediting：共同编辑标记（可选）
  • updated：更新日期范围（可选）
  • groupIds：群组 ID 筛选条件（可选）
  • folderIds：文件夹 ID 筛选条件（可选）
  • likerIds：点赞用户 ID 筛选条件（可选）
  • isArchived：归档标记（可选）
  • sortBy：排序方式（可选）

• get_kibela_note_by_relay_id - 根据 Relay ID 获取笔记

  • id：笔记的 Relay ID（必填）

• get_kibela_note_from_path_or_url - 根据路径或 URL 获取笔记

  • path：笔记的路径或 URL（必填）

• get_kibela_notes - 获取文件夹中的笔记

  • folderId：文件夹 ID（必填）
  • first：从前面开始获取的记录数（可选）
  • last：从后面开始获取的记录数（可选）

• create_kibela_note - 创建新笔记

  • title：笔记标题（必填）
  • content：笔记内容（必填）
  • draft：草稿标记（可选）
  • groupIds：所属群组 ID 列表（必填）
  • folders：文件夹信息（可选）
    • groupId：群组 ID
    • folderName：文件夹名称

• update_kibela_note_content - 更新笔记内容

  • id：笔记 ID（必填）
  • newContent：新内容（必填）
  • baseContent：原始内容（必填）

文件夹操作

• search_kibela_folder - 搜索文件夹

  • query：搜索关键词（必填）

• get_kibela_folder_by_relay_id - 根据 Relay ID 获取文件夹

  • id：文件夹的 Relay ID（必填）
  • first：从前面开始获取的记录数（可选）

• get_kibela_folder_from_path_or_url - 根据路径或 URL 获取文件夹

  • path：文件夹的路径或 URL（必填）
  • first：从前面开始获取的记录数（可选）

• get_kibela_folders - 获取文件夹列表

  • first：从前面开始获取的记录数（可选）
  • last：从后面开始获取的记录数（可选）

• create_kibela_folder - 创建新文件夹

  • groupId：群组 ID（必填）
  • fullName：文件夹的完整路径名称（必填）

• move_kibela_note_to_another_folder - 将笔记移至其他文件夹

  • id：笔记 ID（必填）
  • fromFolder：源文件夹信息（必填）
    • groupId：群组 ID
    • folderName：文件夹名称
  • toFolder：目标文件夹信息（必填）
    • groupId：群组 ID
    • folderName：文件夹名称

• attach_kibela_note_to_folder - 将笔记关联到文件夹

  • id：笔记 ID（必填）
  • folder：文件夹信息（必填）
    • groupId：群组 ID
    • folderName：文件夹名称

评论操作

• create_kibela_comment - 为笔记创建评论

  • content：评论内容（必填）
  • noteId：目标笔记 ID（必填）

• create_kibela_comment_reply - 回复评论

  • content：回复内容（必填）
  • commentId：目标评论 ID（必填）

其他操作

• get_kibela_groups - 获取群组列表

  • first：从前面开始获取的记录数（可选）
  • last：从后面开始获取的记录数（可选）

• get_kibela_feed_sections - 获取 Feed 区块列表

  • kind：Feed 类型（必填）
  • groupId：群组 ID（必填）

可用提示词

审阅提示词

接收 URL 作为输入，并审阅指定的笔记。

输入架构：

{
  url: string; // URL format
}

搜索提示词

接收查询作为输入，并搜索相关信息。

输入架构：

{
  query: string;
}

相关笔记提示词

接收 URL 作为输入，并探索相关笔记。

输入架构：

{
  url: string; // URL format
}

评论反馈提示词

接收 URL 作为输入，并将其评论反馈到笔记中。

输入架构：

{
  url: string; // URL format
}

自定义

你可以按照以下格式准备 JSON 文件，自定义工具描述和提示词。

工具和提示词的键请参见 server.ts。

{
  "tools": {
    "search_kibela_note": {
      "description": "New description"
    }
  },
  "prompts": {
    "review": {
      "prompt": "New review prompt"
    }
  }
}

然后按如下方式将其挂载到容器中：

{
  "mcpServers": {
    "kibela": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-e",
        "KIBELA_ORIGIN",
        "-e",
        "KIBELA_ACCESS_TOKEN",
        "-v",
        "/path/to/kibela-mcp-server-config.json:/usr/src/app/kibela-mcp-server-config.json",
        "ghcr.io/kibela/kibela-mcp-server"
      ],
      "env": {
        "KIBELA_ORIGIN": "https://your-subdomain.kibe.la",
        "KIBELA_ACCESS_TOKEN": "***"
      }
    }
  }
}

开发

docker compose run mcp pnpm install

docker compose up

使用 MCP Inspector 进行测试

npx @modelcontextprotocol/inspector \
  -e KIBELA_ORIGIN=https://your-subdomain.kibe.la \
  -e KIBELA_ACCESS_TOKEN=*** \
  docker compose exec mcp bin/cli.mjs

许可证

此软件包根据 MIT 许可证的条款授权。