API pessoal e MCP

Seus dados do Zukan são seus. Com um token pessoal, scripts, sites e assistentes leem o que você registrou: a coleção, o diário, os cadernos e as estatísticas.

A API lê, e só com a permissão de editar também escreve nos cadernos. Vale só para os dados de quem criou o token, inclusive os privados: guarde o token como uma senha e use num servidor ou script, nunca numa página pública. Criar um token

Autenticação

Mande o token no cabeçalho Authorization de cada chamada:

curl https://zukan.me/api/v1/me \
  -H "Authorization: Bearer zk_..."

Endpoints

GET /api/v1/me: Seu perfil.
GET /api/v1/me/works: Sua coleção: status, nota, resenha, tags e datas. Filtros: status, media, updated_since, q (título).
GET /api/v1/me/log: Seu diário, com progresso e sessões cronometradas. Filtros: since, until, kind, work (slug).
GET /api/v1/me/notebooks: Seus cadernos de obra e livres.
GET /api/v1/me/notebooks/{slug}: Um caderno com o texto em Markdown (o slug do caderno livre ou o da obra).
POST /api/v1/me/notebooks: Cria um caderno livre. Corpo JSON: title, markdown e, opcional, parent (o caderno onde ele fica). Pede a permissão de editar cadernos.
PUT /api/v1/me/notebooks/{slug}: Escreve num caderno livre ou de obra. Corpo JSON: markdown e mode (append acrescenta ao fim, replace substitui). Pede a permissão de editar cadernos.
GET /api/v1/me/stats: Seus números: por status, por mídia, por ano, sessões, sequência.

As listas vêm em páginas: limit (até 200, padrão 50) e offset. O campo next traz o caminho da próxima página, ou null na última. Datas no formato AAAA-MM-DD; notas de 0,5 a 5.

Cada token faz até 120 chamadas por minuto (REST e MCP somados); acima disso, a resposta é 429. A tela de tokens mostra o último uso de cada um.

Das obras saem só o título, o ano, a mídia e os ids do Zukan: capas, sinopses e créditos vêm de fontes que não permitem repassar.

Exemplo: cadernos no Obsidian

Um script que baixa cada caderno como um arquivo .md numa pasta do seu cofre:

#!/usr/bin/env bash
# ZUKAN_TOKEN=zk_... ./zukan-obsidian.sh ~/Obsidian/Zukan
set -euo pipefail
dest="${1:?pasta do cofre}"; mkdir -p "$dest"
api="https://zukan.me/api/v1"
auth="Authorization: Bearer $ZUKAN_TOKEN"
offset=0
while :; do
  page=$(curl -fsS -H "$auth" "$api/me/notebooks?limit=200&offset=$offset")
  for slug in $(echo "$page" | jq -r '.items[].slug'); do
    curl -fsS -H "$auth" "$api/me/notebooks/$slug" | jq -r '.markdown' > "$dest/$slug.md"
  done
  [ "$(echo "$page" | jq '.next')" = "null" ] && break
  offset=$((offset + 200))
done

Exemplo: "Lendo agora" no seu site

No servidor do site (o token não vai para o navegador), as obras em andamento:

const res = await fetch("https://zukan.me/api/v1/me/works?status=in_progress", {
  headers: { Authorization: `Bearer ${process.env.ZUKAN_TOKEN}` },
});
const { items } = await res.json();
// [{ work: { title: "Duna", year: 1965, media_type: "book", url: "..." }, rating: null, ... }]

MCP: seus dados num assistente

O Zukan tem um servidor MCP em https://zukan.me/mcp.

Apps que aceitam OAuth se conectam só com o endereço https://zukan.me/mcp: o app abre uma página do Zukan para você autorizar, sem token (por exemplo, os conectores personalizados do claude.ai).

Para clientes sem OAuth, use um token. No Claude Code:

claude mcp add --transport http zukan https://zukan.me/mcp \
  --header "Authorization: Bearer zk_..."

Em outros clientes que aceitam MCP remoto por HTTP, use o mesmo endereço e o cabeçalho Authorization. As ferramentas de leitura:

search_my_works: busca na sua coleção por título, status e mídia.
get_work_notes: o que você escreveu sobre uma obra (nota, resenha e caderno).
get_my_stats: seus números.
get_reading_log: seu diário, com as sessões.
list_my_notebooks: seus cadernos, de obra e livres.

Experimente perguntar:

"O que eu li de ficção científica este ano e o que achei?"
"Resume o que escrevi no caderno de Duna."
"Quanto tempo passei lendo neste mês?"

Escrever nos cadernos

Com a permissão de editar (um token criado com ela, ou um app que você autorizou a editar), o MCP ganha duas ferramentas:

create_notebook: cria um caderno livre, com título e texto em Markdown, opcionalmente dentro de outro.
update_notebook: escreve num caderno livre ou de obra: mode append acrescenta ao fim, replace substitui. Toda mudança fica no histórico do caderno.

Pela API REST, o mesmo: POST /api/v1/me/notebooks com {"title","markdown","parent"} e PUT /api/v1/me/notebooks/{slug} com {"markdown","mode":"append"|"replace"}. Um token sem a permissão recebe 403 insufficient_scope.

curl -X PUT https://zukan.me/api/v1/me/notebooks/meu-caderno \
  -H "Authorization: Bearer zk_..." \
  -H "Content-Type: application/json" \
  -d '{"markdown": "\n## Hoje\nTerminei o capítulo 3.", "mode": "append"}'

Escreva [[Título]] para linkar o seu caderno com esse título, ou uma obra do catálogo.