Apple Books

Acesse e gerencie sua biblioteca no Apple Books.

GitHub

Experimente este MCPPatrocinado

Documentação

Apple Books MCP

Servidor Model Context Protocol (MCP) para Apple Books.

Visão geral

Continue de onde parou — Claude vê o capítulo em que você está e seu texto, além dos destaques recentes no livro.
Expanda qualquer destaque — obtenha a explicação do parágrafo ao redor no contexto, com a âncora exata que você marcou exibida em «...».
Revise um livro — recupere seus destaques, agrupe-os por tema e mostre suas próprias citações de volta para você.
Reflita sobre sua leitura — padrões entre livros, ideias recorrentes em seus destaques, aquilo que realmente atrai você.

https://github.com/user-attachments/assets/77a5a29b-bfd7-4275-a4af-8d6c51a4527e

E muito mais!

Ferramentas Disponíveis

Coleções

Ferramenta	Descrição	Parâmetros
list_all_collections	Listar todas as coleções	limit?: int
get_collection_books	Obter todos os livros de uma coleção	collection_id: str
describe_collection	Obter detalhes de uma coleção	collection_id: str
search_collections_by_title	Buscar coleções por título	title: str

Edição de coleções (opt-in)

Desativado por padrão. Ative adicionando --enable-writes aos argumentos do servidor:

"args": ["apple-books-mcp@latest", "--enable-writes"]

A Apple não fornece API de automação para coleções, então estas escrevem diretamente no banco de dados da biblioteca — com salvaguardas: cada escrita é recusada enquanto o Books estiver aberto, faz um backup automático seguro para WAL primeiro (~/.py_apple_books/backups/), valida o esquema e aborta em caso de divergência, e só toca em coleções criadas pelo usuário (além da associação "Quero Ler"). Excluir uma coleção nunca exclui os livros nela.

⚠️ Se a sincronização do iCloud para coleções estiver ativada, edições diretas podem não se propagar para outros dispositivos e podem ser revertidas por uma ressincronização na nuvem.

Ferramenta	Descrição	Parâmetros
create_collection	Criar uma nova coleção	title: str, details?: str
rename_collection	Renomear uma coleção criada pelo usuário	collection_id: int, new_title: str
delete_collection	Excluir uma coleção criada pelo usuário (livros intactos)	collection_id: int
add_book_to_collection	Adicionar um livro a uma coleção (idempotente)	collection_id: int, book_id: int
remove_book_from_collection	Remover um livro de uma coleção (idempotente)	collection_id: int, book_id: int

Livros

Ferramenta	Descrição	Parâmetros
list_all_books	Listar todos os livros	limit?: int
describe_book	Obter detalhes de um livro específico (metadados, progresso, contagem de anotações, descrição)	book_id: str
list_annotations	Obter todas as anotações de um livro (id + texto + capítulo por linha, ordenadas por capítulo)	book_id: int, limit?: int
search_books_by_title	Buscar livros por título	title: str
get_books_by_genre	Obter livros por gênero (correspondência por substring)	genre: str, limit?: int

Status de Leitura

Ferramenta	Descrição	Parâmetros
get_books_in_progress	Obter livros atualmente em leitura	limit?: int
get_finished_books	Obter livros que foram concluídos	limit?: int
get_unstarted_books	Obter livros ainda não iniciados	limit?: int
get_recently_read_books	Obter livros abertos mais recentemente	limit?: int (padrão: 10)

Anotações

Ferramenta	Descrição	Parâmetros
list_all_annotations	Navegar por todas as anotações agrupadas por livro, mais recentes primeiro	limit?: int
recent_annotations	Obter anotações mais recentes (planas, com data + livro por linha)	limit?: int (padrão: 10)
describe_annotation	Obter detalhes completos de uma única anotação	annotation_id: str
get_annotation_context	Janela de texto ao redor de um destaque (o parágrafo em que está), com o destaque marcado `«...»`	annotation_id: int, chars_before?: int (padrão: 500), chars_after?: int (padrão: 500)
get_highlights_by_color	Destaques de uma cor específica, agrupados por livro	color: str, limit?: int
search_notes	Buscar notas do usuário (mostra destaque + nota inline)	note: str, limit?: int
search_annotations	Buscar em destaques + notas + texto ao redor	text: str, limit?: int
get_annotations_by_date_range	Anotações dentro de um intervalo de datas (planas, com data + livro por linha)	after?: YYYY-MM-DD, before?: YYYY-MM-DD, limit?: int

Estatísticas da Biblioteca

Ferramenta	Descrição	Parâmetros
get_library_stats	Obter resumo da biblioteca com estatísticas de leitura	None

Conteúdo do Livro

Funciona apenas para EPUBs sem DRM (livros importados, Project Gutenberg, Standard Ebooks, etc.). Compras na Apple Books Store são protegidas por FairPlay e retornam um erro claro. Livros somente no iCloud retornam uma dica de "não baixado".

Ferramenta	Descrição	Parâmetros
list_book_chapters	Sumário de um livro (títulos dos capítulos, ordem, aninhamento)	book_id: int
get_chapter_content	Conteúdo em texto simples de um capítulo, com fatiamento opcional por `offset` + `max_chars`	book_id: int, chapter_id: str, offset?: int, max_chars?: int
get_current_reading_position	O capítulo em que o usuário parou de ler por último (via marcador automático CFI do Apple Books)	book_id: int

Recursos Disponíveis

Objetos de dados anexáveis acessíveis pelo seletor de recursos do Claude Desktop.

Recurso	URI	Descrição
Leitura Atual	`apple-books://currently-reading`	O livro que você está lendo agora — livro em andamento aberto mais recentemente, com metadados, o capítulo em que você parou mais uma prévia de seu texto (para EPUBs sem DRM) e anotações recentes. Anexe a qualquer conversa para focar Claude na sua leitura atual.

Prompts Disponíveis

Fluxos de trabalho com um clique, acessíveis pelo seletor de prompts do Claude Desktop.

Prompt	Descrição	Argumentos
weekly_digest	Resumir o que li e destaquei na última semana	days?: int (padrão: 7)
library_snapshot	Uma reflexão sobre toda a minha vida de leitura	None
revisit_book	Revisitar suas notas e destaques de um livro específico	book_title: str

Instalação

Usando uv (recomendado)

uvx pode ser usado para executar diretamente o apple-books-mcp (sem instalá-lo).

brew install uv  # for macos
uvx apple-books-mcp

Usando pip

pip install apple-books-mcp

Após a instalação, você pode executar o servidor usando:

python -m apple_books_mcp

Usando Docker

docker run -v ~/Library/Containers/com.apple.iBooksX/Data/Documents:/root/Library/Containers/com.apple.iBooksX/Data/Documents:ro ghcr.io/vgnshiyer/apple-books-mcp:latest

Solicitação de permissão na primeira execução (macOS)

No primeiro uso, o macOS perguntará se uvx (ou python / docker, dependendo de como você iniciou) pode "acessar dados de outros aplicativos." Clique em Permitir — o MCP lê o contêiner privado do Apple Books em ~/Library/Containers/com.apple.iBooksX/, que o macOS trata como dados em sandbox de outro aplicativo. O acesso é somente leitura e limitado a esse contêiner; o servidor inicia com sucesso de qualquer forma, mas sem permissão todas as ferramentas retornam vazias.

macOS permission prompt: uvx would like to access data from other apps. Don't Allow / Allow.

Configuração

Configuração do Claude Desktop

Usando uvx (recomendado)

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "uvx",
            "args": [ "apple-books-mcp@latest" ]
        }
    }
}

Usando python

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "python",
            "args": ["-m", "apple_books_mcp"]
        }
    }
}

Usando Docker

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "-v", "~/Library/Containers/com.apple.iBooksX/Data/Documents:/root/Library/Containers/com.apple.iBooksX/Data/Documents:ro",
                "ghcr.io/vgnshiyer/apple-books-mcp:latest"
            ]
        }
    }
}

Recursos Futuros

Acesso a conteúdo PDF (atualmente apenas EPUB)
contexto de anotação mais completo via resolução de CFI → parágrafo

Contribuição

Obrigado por considerar contribuir com este projeto!

Desenvolvimento

Se você clonou este repositório, pode testá-lo usando o Claude Desktop com a configuração abaixo:

Use uv venv para criar um ambiente virtual e instalar as dependências.

uv venv
uv sync

Depuração

Com o Claude Desktop

{
    "mcpServers": {
        "apple-books-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/apple-books-mcp/",
                "run",
                "apple_books_mcp",
                "-v"
            ]
        }
    }
}

Com o inspector

npx @modelcontextprotocol/inspector uvx apple-books-mcp

Abrindo Issues

Se você encontrar um bug, tiver uma solicitação de recurso ou quiser discutir algo relacionado ao projeto, abra uma issue no repositório do GitHub. Ao abrir uma issue, forneça:

Relatórios de Bug: Descreva o problema em detalhes. Inclua etapas para reproduzir o bug, se possível, junto com mensagens de erro ou capturas de tela.

Solicitações de Recurso: Explique claramente o novo recurso que você gostaria de ver adicionado ao projeto. Forneça contexto sobre por que esse recurso seria benéfico.

Discussões Gerais: Sinta-se à vontade para iniciar discussões sobre tópicos mais amplos relacionados ao projeto.

Contribuindo

1️⃣ Faça um fork do repositório no GitHub https://github.com/vgnshiyer/apple-books-mcp
2️⃣ Crie um novo branch para suas alterações (git checkout -b feature/my-new-feature).
3️⃣ Faça suas alterações e teste-as minuciosamente.
4️⃣ Envie suas alterações e abra um Pull Request para main.

Forneça um título e uma descrição claros para suas alterações.

Licença

Apple Books MCP é licenciado sob a licença Apache 2.0. Consulte o arquivo LICENSE para obter detalhes.