Readwise Reader

Um servidor MCP para a API do Readwise Reader acessar e gerenciar seus artigos e destaques.

GitHub
47

Documentação

Servidor MCP do Readwise Reader

Um servidor Model Context Protocol (MCP) para a API do Readwise Reader, construído com TypeScript e o SDK oficial do Claude.

Recursos

  • Autenticação Segura: Usa variáveis de ambiente para armazenamento de tokens
  • Gerenciamento de Documentos: Salvar, listar, atualizar e excluir documentos com metadados completos
  • Gerenciamento de Tags: Listar e filtrar por tags
  • Filtragem Avançada: Filtrar documentos por localização, categoria, tags e mais
  • Suporte a Paginação: Lidar com grandes coleções de documentos
  • Conteúdo Amigável para LLM: Conteúdo HTML convertido automaticamente em texto limpo usando r.jina.ai
  • Acesso Completo aos Dados: Retorna informações completas do documento, incluindo conteúdo, metadados e carimbos de data/hora

Documentação da API

Para informações detalhadas sobre os endpoints, parâmetros e exemplos da API do Readwise Reader, consulte a documentação oficial da API:

📖 Documentação da API do Readwise Reader

Este servidor MCP implementa todos os endpoints principais descritos na documentação oficial.

Instalação

npm install
npm run build

Configuração

Com Claude Desktop

  1. Compile o servidor MCP:

    npm install
npm run build

  2. Obtenha seu token de acesso do Readwise em: https://readwise.io/access_token

  3. Adicione o servidor à configuração do Claude Desktop. Abra as configurações do Claude Desktop e adicione isto à configuração dos servidores MCP:

    macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

    {
  "mcpServers": {
    "readwise-reader": {
      "command": "node",
      "args": ["/path/to/your/reader_readwise_mcp/dist/index.js"],
      "env": {
        "READWISE_TOKEN": "your_readwise_access_token_here"
      }
    }
  }
}

    Substitua:

    • /path/to/your/reader_readwise_mcp pelo caminho real para o diretório deste projeto
    • your_readwise_access_token_here pelo seu token de acesso real do Readwise

  4. Reinicie o Claude Desktop

Ferramentas Disponíveis

readwise_save_document

Salvar um documento (URL ou conteúdo HTML) no Readwise Reader.

Parâmetros:

  • url (obrigatório): URL do documento a ser salvo
  • html (opcional): Conteúdo HTML do documento
  • tags (opcional): Lista de tags para adicionar
  • location (opcional): Localização para salvar (new, later, shortlist, archive, feed)
  • category (opcional): Categoria do documento (article, book, tweet, pdf, email, youtube, podcast)

readwise_list_documents

Listar documentos do Readwise Reader com filtragem opcional. Retorna informações completas do documento, incluindo metadados e conteúdo de texto amigável para LLM.

Parâmetros:

  • id (opcional): Filtrar por ID específico do documento
  • updatedAfter (opcional): Filtrar documentos atualizados após esta data (ISO 8601)
  • location (opcional): Filtrar por localização do documento
  • category (opcional): Filtrar por categoria do documento
  • tag (opcional): Filtrar por nome da tag
  • pageCursor (opcional): Cursor de página para paginação
  • withHtmlContent (opcional): ⚠️ AVISO DE DESEMPENHO: Incluir conteúdo HTML na resposta. Isso diminui significativamente a API. Use apenas quando explicitamente solicitado pelo usuário ou quando o HTML bruto for especificamente necessário para a tarefa.
  • withFullContent (opcional): ⚠️ AVISO DE DESEMPENHO: Incluir conteúdo de texto convertido completo na resposta. Isso diminui significativamente a API, pois busca e processa o conteúdo de cada documento. Use apenas quando explicitamente solicitado pelo usuário ou quando o conteúdo do documento for especificamente necessário para análise/leitura. Padrão: false por desempenho.

Retorna: Objetos de documento completos com todos os campos disponíveis:

  • id, title, author, url, source_url, summary
  • published_date, image_url, location, category
  • tags, created_at, updated_at
  • content: Conteúdo de texto amigável para LLM (convertido de source_url ou url via r.jina.ai)

readwise_update_document

Atualizar um documento no Readwise Reader.

Parâmetros:

  • id (obrigatório): ID do documento para atualizar
  • title (opcional): Novo título
  • author (opcional): Novo autor
  • summary (opcional): Novo resumo
  • published_date (opcional): Nova data de publicação (ISO 8601)
  • image_url (opcional): Nova URL da imagem
  • location (opcional): Nova localização
  • category (opcional): Nova categoria

readwise_delete_document

Excluir um documento do Readwise Reader.

Parâmetros:

  • id (obrigatório): ID do documento para excluir

readwise_list_tags

Listar todas as tags do Readwise Reader.

Parâmetros: Nenhum

readwise_topic_search

Pesquisar documentos no Readwise Reader por tópico usando correspondência regex em título, resumo, notas e tags.

Parâmetros:

  • searchTerms (obrigatório): Lista de termos de pesquisa para corresponder ao conteúdo do documento (correspondência regex sem diferenciar maiúsculas de minúsculas)

Retorna: Resultados da pesquisa com documentos correspondentes, incluindo:

  • Termos de pesquisa usados
  • Número total de correspondências
  • Objetos de documento completos com todos os metadados disponíveis (mesmos campos que readwise_list_documents)

Autenticação

O servidor requer um token de acesso do Readwise fornecido por meio da variável de ambiente READWISE_TOKEN. Este token é usado para autenticar todas as solicitações de API ao Readwise Reader.

Nota de Segurança: O token é armazenado na sua configuração MCP e nunca é exposto por meio do Claude ou da interface de ferramentas.

Limites de Requisições

  • Padrão: 20 solicitações/minuto
  • CREATE/UPDATE de documento: 50 solicitações/minuto
  • Respostas 429 incluem o cabeçalho "Retry-After"

Licença

MIT