Anki MCP Manga

Anki电报机器人

Telegram机器人，根据漫画截图和文字创建日语词汇Anki抽认卡。发送漫画页面的照片，机器人会提取词汇，用图像创建卡片，并同步到您的所有设备。

由LangGraph ReAct代理（通过OpenRouter）和在Docker中运行的无头Anki集合提供支持。

卡片类型

汉字卡片 （甲板： Japones KANJI):

• 正面：汉字或单词
• 返回：阅读（平假名）+含义

漫画发音卡 （甲板： Japones Vocab Mangas):

• 正面：漫画面板截图+目标单词所在的日语句子 大胆
• 返回：包含目标词的完整句子翻译 大胆

建筑

Telegram User
    | photo + caption / text
    v
+-----------------------------+
|  anki-bot container         |
|                             |
|  aiogram (polling) ---------+--> Telegram API (outbound)
|      |                      |
|  LangGraph ReAct Agent -----+--> OpenRouter API (outbound)
|      |                      |
|  Anki Tools (direct calls)  |
|      |                      |
|  AnkiManager + SyncManager -+--> anki-sync:8080 (internal)
|      |                      |
|  /data (collection + media) |
+-----------------------------+

+-----------------------------+
|  anki-sync container        |
|  python -m anki.syncserver  |
|  :8080 (Tailscale for       |
|   phone/desktop clients)    |
+-----------------------------+

bot容器上没有入站端口。它使用Telegram轮询（仅限出站）。同步服务器暴露给您的手机/桌面Anki客户端的Tailscale。

设置

先决条件

• Docker（或Podman）
• Telegram机器人代币（来自 @植物学家)
• 一 开放路由 API密钥

1.克隆和配置

git clone https://github.com/ThiagoLira/anki-mcp-manga.git
cd anki-mcp-manga

cp .env.example .env

编辑 .env 并填写所需值：

# Required: get this from @BotFather on Telegram
TELEGRAM_BOT_TOKEN=your-bot-token-here

# Required: get this from openrouter.ai/keys
OPENROUTER_API_KEY=your-openrouter-key-here

获取Telegram机器人令牌

1. 打开电报和消息 @植物学家
2. 发送 /newbot，选择一个名称和用户名
3. 复制它给你的令牌 TELEGRAM_BOT_TOKEN

限制访问（可选）

要限制谁可以使用机器人，请设置 ALLOWED_TELEGRAM_USER_IDS 以逗号分隔的Telegram用户ID列表。留空以允许任何人。

要查找您的用户ID，请发送消息 @用户信息机器人 在Telegram上。

ALLOWED_TELEGRAM_USER_IDS=123456789,987654321

2.启动堆栈

docker compose up --build -d

这将启动两个容器：

• 安基机器人 --Telegram机器人（无暴露端口）
• anki同步 （：8080）--自托管Anki同步服务器

检查日志以确认机器人已启动：

docker compose logs -f anki-bot

3.与机器人对话

在Telegram中打开你的机器人，然后尝试：

• /start --欢迎留言
• /stats --收集统计
• /decks --列出所有甲板
• 发送一条短信，如 "Create a card for 食べる (たべる, to eat)" --创建汉字卡并同步
• 发送漫画截图——代理提取词汇，用图像创建漫画词汇卡，并同步

4.将Anki客户端连接到同步服务器

在您的手机或台式机Anki上（必须在同一网络上，或使用Tailscale）：

1. 首选项>同步>自托管同步服务器
2. 网址： http://:8080
3. 用户名/密码：来自您的 .env (SYNC_USER / SYNC_PASSWORD，默认值 user / password)

如果你使用Tailscale，URL将是 http://100.x.x.x:8080 或 http://..ts.net:8080.

k3s部署（Kubernetes）

该堆栈可以在k3s上运行，而不是在普通的Docker Compose上运行。这是在上使用的设置 teagolab-1 Tailnet服务器。

初始设置

安装k3s并配置kubectl：

curl -sfL https://get.k3s.io | sh -
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
echo 'export KUBECONFIG=~/.kube/config' >> ~/.bashrc

从您的 .env:

kubectl create namespace anki
kubectl create secret generic anki-env -n anki \
  --from-env-file=.env

构建、导入映像和部署：

docker compose build
docker save anki_mcp-anki-bot | sudo k3s ctr images import --all-platforms -
docker save anki_mcp-anki-sync | sudo k3s ctr images import --all-platforms -
kubectl apply -f k8s/anki.yaml

更改后重新部署

从您的开发机器：

ssh teagolab-1 "cd repos/anki_mcp && git pull && ./k8s/deploy.sh"

或者直接在服务器上：

cd ~/repos/anki_mcp
git pull
./k8s/deploy.sh

Kubernetes仪表板

仪表板部署在 https://teagolab-1:30443 （可从任何Tailnet设备访问）。登录令牌位于 ~/.kube/dashboard-token 在服务器上。

数据管理

数据所在之处

data/
  mcp/                    <-- bot's Anki collection
    collection.anki2
    collection.media/     <-- images (manga panels as .webp)
  sync/                   <-- sync server data
    user/

这 data/ 目录为gitignored。这是你唯一需要备份的状态。

导入现有收藏

docker compose stop anki-bot

cp ~/.local/share/Anki2/User\ 1/collection.anki2 data/mcp/
cp -a ~/.local/share/Anki2/User\ 1/collection.media/. data/mcp/collection.media/

docker compose start anki-bot

然后向机器人发送任何消息，使其触发同步，或重新启动堆栈。

迁移回AnkiWeb

1. 打开Anki桌面
2. 从首选项中删除自定义同步服务器URL
3. 同步到AnkiWeb--选择“上传到AnkiWeb”

环境变量

发展

# Create venv (Python 3.11 required by anki package)
uv venv --python 3.11 .venv
source .venv/bin/activate
uv sync --extra dev

# Run tests
TELEGRAM_BOT_TOKEN=test OPENROUTER_API_KEY=test pytest tests/ -v

# Run bot locally (without Docker)
source .env
python -m src.bot