Hardcover MCP

Converse com sua biblioteca Hardcover a partir de qualquer assistente de IA.

Documentação

hardcover-mcp

Fale com sua biblioteca do Hardcover a partir de qualquer assistente de IA.

O hardcover-mcp conecta sua biblioteca do Hardcover a assistentes de IA como Claude e Copilot. Pesquise livros, atualize seu status de leitura, gerencie listas, explore séries — tudo por meio de conversa natural, em vez de clicar em menus.

O que você pode dizer

"O que está na minha lista de leitura atual?"

"Adicione Project Hail Mary à minha biblioteca como leitura atual"

"Pesquise livros de Brandon Sanderson"

"Consulte o ISBN 9780547928227"

"Crie uma lista chamada 'Leitura de Verão' e adicione O Hobbit a ela"

"Mostre-me a série Stormlight Archive em ordem de leitura"

"Mova Project Hail Mary e The Martian para leitura atual"

"Quais livros Andy Weir escreveu? Adicione os que ainda não li à minha lista de quero ler"

"Compare minha avaliação de Dune com a média do Hardcover"

O que está incluído

Acompanhamento da biblioteca — status, avaliações, datas de leitura
Gerenciamento de listas — criar, editar, adicionar/remover livros
Descoberta — pesquisar livros, autores, séries, edições e mais
Informações da conta — seu perfil e estatísticas de leitura

Segurança e controle

Você controla sua chave de API — ela permanece na sua máquina, nunca compartilhada com terceiros
Executa localmente por meio do seu cliente MCP — nenhum servidor externo envolvido
As ações só acontecem quando solicitadas explicitamente — nada é executado em segundo plano
Você revisa prompts e saídas no seu cliente antes de qualquer envio

Início Rápido

Instale o uv (um executor rápido de pacotes Python — a configuração leva segundos).
Obtenha um token de API em hardcover.app/account/api.
Adicione a configuração abaixo ao seu cliente MCP — nenhuma instalação manual é necessária, o uvx cuida disso.

VS Code

Adicione a .vscode/mcp.json:

{
  "servers": {
    "hardcover": {
      "command": "uvx",
      "args": ["hardcover-mcp"],
      "env": {
        "HARDCOVER_API_TOKEN": "<your token>"
      }
    }
  }
}

Claude Desktop

Adicione a claude_desktop_config.json:

{
  "mcpServers": {
    "hardcover": {
      "command": "uvx",
      "args": ["hardcover-mcp"],
      "env": {
        "HARDCOVER_API_TOKEN": "<your token>"
      }
    }
  }
}

Ferramentas

Navegar e descobrir

O que você pode fazer	Ferramenta
Pesquisar livros, autores, séries e mais	`search_books`
Consultar um livro por título ou ID	`get_book`
Consultar uma edição específica por ISBN ou ASIN	`get_edition`
Explorar uma série em ordem de leitura	`get_series`
Navegar pelo catálogo de um autor	`get_author`

Sua biblioteca

O que você pode fazer	Ferramenta
Ver seu perfil e contagem de livros	`me`
Obter estatísticas de leitura (totais, avaliações, livros lidos por ano)	`get_reading_stats`
Obter suas metas de leitura ativas e progresso	`get_reading_goal`
Navegar pela sua biblioteca, filtrar por status, intervalo de datas ou ordenar por avaliação/data	`get_user_library`
Verificar seu status/avaliação de um livro específico (inclui configuração de privacidade)	`get_user_book`
Listar suas resenhas	`get_user_reviews`
Ler suas entradas de diário (notas, citações, eventos de status)	`get_reading_journal`
Listar livros que você possui, com detalhes da edição	`get_owned_books`
Criar ou atualizar uma meta de leitura (livros/páginas, intervalo de datas)	`set_reading_goal`
Adicionar um livro ou atualizar seu status, avaliação, resenha, notas, privacidade e edição	`set_user_book`
Marcar uma edição como possuída ou não possuída	`set_edition_owned`
Registrar datas de leitura e progresso (páginas, tempo de audiolivro)	`add_user_book_read` / `update_user_book_read`
Remover um livro ou entrada de leitura	`delete_user_book` / `delete_user_book_read`
Criar ou excluir uma entrada de nota/citação no diário	`add_journal_entry` / `delete_journal_entry`

Listas

O que você pode fazer	Ferramenta
Ver todas as suas listas	`get_my_lists`
Ver uma lista específica com seus livros	`get_list`
Criar, renomear ou excluir uma lista	`create_list` / `update_list` / `delete_list`
Adicionar ou remover livros de uma lista	`add_book_to_list` / `remove_book_from_list`

Desenvolvimento

git clone https://github.com/kristianedlund/hardcover-mcp.git
cd hardcover-mcp
uv sync

Verificações de lint e formatação (usando Ruff):

uv run ruff check src/
uv run ruff format --check src/

Execute os testes:

uv run pytest tests/ -v

Testes de Integração

Os testes de integração acessam a API ao vivo do Hardcover e exigem um token válido. Eles são ignorados automaticamente em CI e quando o token está ausente.

Para executá-los localmente, crie um arquivo .env com seu token:

HARDCOVER_API_TOKEN=your_token_here

Em seguida, execute:

uv run pytest tests/integration/ -v

Os testes de escrita seguem um ciclo de vida criar → verificar → excluir, para que a conta permaneça inalterada.

Contribuindo

Contribuições são bem-vindas! Por favor:

Abra uma issue primeiro para discutir a mudança.
Faça um fork do repositório e crie uma branch (feature/short-description ou fix/short-description).

Execute lint e testes antes de enviar:

uv run ruff check src/
uv run ruff format --check src/
uv run pytest tests/ -v

Mantenha os PRs focados — uma mudança por PR.
Use prefixos de commit convencionais: feat:, fix:, chore:, docs:.

Limite de Taxa

A API do Hardcover permite 60 solicitações por minuto. O servidor lida com isso automaticamente — ele enfileira solicitações e tenta novamente se necessário. Você não deve atingir esse limite no uso normal.

Solução de Problemas

Problema	Correção
"API token is not set"	Adicione seu token à configuração (veja Início Rápido acima)
"Access is denied" no Windows	Adicione `"UV_LINK_MODE": "copy"` ao bloco `env` na sua configuração
Erros lentos ou repetidos	O servidor tenta novamente automaticamente — aguarde um momento e tente de novo
Resultados inesperados	Verifique se há uma versão mais recente: a API do Hardcover pode ter mudado

Aviso Legal

Projeto não oficial. Não afiliado ao Hardcover.