Kanka MCP - Model Context Protocol Server for Kanka API

Kanka MCP - Kanka API 的模型上下文协议服务

本项目提供一个用于与 Kanka API 交互的 MCP（模型上下文协议）服务。它支持 AI 助手管理 Kanka 世界构建项目中的战役、角色、地点、帖子、笔记和日志。

功能

该服务提供以下工具：

• 战役：列出用户的所有战役
• 角色：列出、获取、创建、更新和删除角色
• 地点：列出、获取、创建、更新和删除地点
• 帖子：列出、获取、创建、更新和删除任意实体的帖子
• 笔记：列出、获取、创建、更新和删除笔记
• 日志：列出、获取、创建、更新和删除日志

所有创建和更新操作都会正确处理描述字段中的 HTML 内容，并支持隐私设置。

安装

前置条件

• Python 3.10+

安装

1. 克隆此仓库：

   git clone https://github.com/yourusername/kanka_mcp.git
   cd kanka_mcp
   

2. 安装依赖：

   pip install requests mcp[cli]
   

   或者，如果你有 pyproject.toml 文件：

   pip install .
   

配置

你需要设置 KANKA_API_KEY 环境变量，并将其值设为你的 Kanka API 密钥：

export KANKA_API_KEY=your_kanka_api_key

获取 Kanka API 密钥的方法：

1. 登录你的 Kanka 账户
2. 前往“账户设置”
3. 进入“API”部分
4. 创建或复制你的 API 令牌

用法

运行 MCP 服务

直接运行服务：

python kanka_mcp.py

添加到 MCP 服务配置

将以下内容添加到 MCP 服务配置中：

"kanka": {
    "command": "python",
    "args": [
        "FULL_PATH_TO_SCRIPT_FOLDER/kanka_mcp.py"
    ],
    "env": {
        "KANKA_API_KEY": "YOUR_KANKA_API_KEY"
    }
}

将 FULL_PATH_TO_SCRIPT_FOLDER 替换为包含 kanka_mcp.py 脚本的目录的绝对路径，并将 YOUR_KANKA_API_KEY 替换为你的实际 Kanka API 密钥。

可用工具

战役

• show_campaigns()：列出用户有权访问的所有战役。

角色

• list_characters(campaign_id)：列出战役中的所有角色。
• get_character(campaign_id, character_id)：按 ID 获取指定角色。
• create_character(campaign_id, name, ...)：创建新角色。
• update_character(campaign_id, character_id, ...)：更新现有角色。
• delete_character(campaign_id, character_id)：删除角色。

地点

• list_locations(campaign_id)：列出战役中的所有地点。
• get_location(campaign_id, location_id)：按 ID 获取指定地点。
• create_location(campaign_id, name, ...)：创建新地点。
• update_location(campaign_id, location_id, ...)：更新现有地点。
• delete_location(campaign_id, location_id)：删除地点。

帖子

• list_posts(campaign_id, entity_id)：列出某个实体的所有帖子。
• get_post(campaign_id, entity_id, post_id)：按 ID 获取指定帖子。
• create_post(campaign_id, entity_id, name, ...)：创建新帖子。
• update_post(campaign_id, entity_id, post_id, ...)：更新现有帖子。
• delete_post(campaign_id, entity_id, post_id)：删除帖子。

笔记

• list_notes(campaign_id)：列出战役中的所有笔记。
• get_note(campaign_id, note_id)：按 ID 获取指定笔记。
• create_note(campaign_id, name, ...)：创建新笔记。
• update_note(campaign_id, note_id, ...)：更新现有笔记。
• delete_note(campaign_id, note_id)：删除笔记。

日志

• list_journals(campaign_id)：列出战役中的所有日志。
• get_journal(campaign_id, journal_id)：按 ID 获取指定日志。
• create_journal(campaign_id, name, ...)：创建新日志。
• update_journal(campaign_id, journal_id, ...)：更新现有日志。
• delete_journal(campaign_id, journal_id)：删除日志。

许可证

本项目遵循 LICENSE 文件中指定的条款授权。