convez.ai
MCP ServerIntegração & APIsIntermediário
ngpestelos

Readwise MCP Server

ngpestelos/readwise-mcp-server

Sincronize seus highlights do Readwise com eficiência de tokens

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP minimalista em Python para integração com Readwise, otimizado para eficiência de tokens. Implementação single-file com 10 ferramentas essenciais para importar, sincronizar e buscar highlights de livros, artigos e tweets diretamente no Claude.

Instalação

$npx convez-ai ngpestelos/readwise-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
1
Contribuidores
1

Casos de uso

  • Importar highlights diários para revisão no vault PARA
  • Sincronizar retrospectivamente highlights até uma data específica
  • Pesquisar highlights por texto em toda a biblioteca
  • Exportar highlights de livros específicos para análise
  • Integrar fluxo de leitura com Claude para análise contextual

Veredito

MCP server robusto e bem-pensado para Readwise com arquitetura enxuta em Python. Ideal para quem mantém vault PARA e quer sincronização eficiente de highlights sem overhead de tokens.

README

A tradução para o português deste README ainda está na fila.

Readwise MCP Server

Minimal Python MCP server for Readwise integration - token-efficient, single-file implementation using FastMCP.

Features

  • Token-efficient: 10 essential tools (vs 13+ in Node.js version)
  • Single-file architecture: ~1,000 lines of code
  • Proven logic: Reuses battle-tested deduplication and pagination from backfill script
  • State compatibility: Preserves existing state file format
  • Smart optimization: Uses synced ranges to skip unnecessary API calls
  • Highlights import: Dedicated tools for importing all highlights with temporal organization

Installation

1. Clone repository

git clone https://github.com/ngpestelos/readwise-mcp-server.git
cd readwise-mcp-server

2. Create virtual environment

python3 -m venv venv
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment variables

Set these in your .mcp.json file:

  • READWISE_TOKEN: Your Readwise API token
  • VAULT_PATH: Path to your PARA vault (e.g., /path/to/your/vault)

Configuration

Update .mcp.json

Add or update the readwise entry in your vault's .mcp.json:

{
  "mcpServers": {
    "readwise": {
      "command": "/absolute/path/to/readwise-mcp-server/venv/bin/python",
      "args": ["/absolute/path/to/readwise-mcp-server/server.py"],
      "env": {
        "READWISE_TOKEN": "your_token_here",
        "VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Replace the paths with your actual installation locations.

Tools Reference

1. readwise_daily_review()

Fetch today's highlights and save to Daily Reviews directory.

Parameters: None

Returns:

{
  "status": "success",
  "count": 42,
  "file": "/path/to/daily-review.md"
}

Example:

Call readwise_daily_review()

2. readwise_import_recent(category="tweet", limit=20)

Import recent documents since last import with automatic deduplication.

Parameters:

  • category (string, optional): Document category (default: "tweet")
  • limit (int, optional): Maximum documents to fetch (default: 20)

Returns:

{
  "status": "success",
  "imported": 5,
  "skipped": 15,
  "total_analyzed": 20
}

Example:

Call readwise_import_recent(category="article", limit=50)

3. readwise_backfill(target_date, category="tweet")

Paginate backwards to target date with synced range optimization.

Parameters:

  • target_date (string, required): Target date in YYYY-MM-DD format
  • category (string, optional): Document category (default: "tweet")

Returns:

{
  "status": "success",
  "imported": 67,
  "skipped": 433,
  "pages": 10,
  "reached_target": true
}

Example:

Call readwise_backfill(target_date="2026-01-01")

4. readwise_book_highlights(title=None, book_id=None)

Get highlights for a specific book.

Parameters:

  • title (string, optional): Book title to search for
  • book_id (string, optional): Specific book ID

Returns:

{
  "status": "success",
  "count": 15,
  "highlights": [...]
}

Example:

Call readwise_book_highlights(title="Atomic Habits")

5. readwise_search_highlights(query, limit=50)

Search highlights by text query.

Parameters:

  • query (string, required): Search query
  • limit (int, optional): Maximum results (default: 50)

Returns:

{
  "status": "success",
  "count": 8,
  "highlights": [...]
}

Example:

Call readwise_search_highlights(query="productivity")

6. readwise_state_info()

Show current import state and synced ranges.

Parameters: None

Returns:

{
  "status": "success",
  "last_import": "2026-01-22T04:29:12Z",
  "oldest_imported": "2026-01-01",
  "synced_ranges": [...],
  "backfill_in_progress": false,
  "documents_on_disk": 1044,
  "documents_with_ids": 614
}

Example:

Call readwise_state_info()

7. readwise_init_ranges()

Scan filesystem to build synced_ranges from existing documents.

Parameters: None

Returns:

{
  "status": "success",
  "range": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-01-21T00:00:00Z",
    "doc_count": 614
  },
  "documents_analyzed": 614
}

Example:

Call readwise_init_ranges()

8. readwise_reset_state(clear_ranges=False)

Clear state file (optionally preserve synced_ranges).

Parameters:

  • clear_ranges (bool, optional): Whether to clear synced ranges (default: False)

Returns:

{
  "status": "success",
  "message": "State reset",
  "cleared_ranges": false
}

Example:

Call readwise_reset_state(clear_ranges=True)

9. readwise_import_recent_highlights(limit=100)

Import recent highlights across all sources since last import.

Parameters:

  • limit (int, optional): Maximum highlights to fetch (default: 100)

Returns:

{
  "status": "success",
  "imported": 42,
  "skipped": 58,
  "total_analyzed": 100
}

Example:

Call readwise_import_recent_highlights(limit=200)

Saves to: 2 Resources/Readwise/Highlights/YYYYMMDD-HHMMSS [Source Title] highlight.md

10. readwise_backfill_highlights(target_date)

Paginate highlights backwards to target date with synced range optimization.

Parameters:

  • target_date (string, required): Target date in YYYY-MM-DD format

Returns:

{
  "status": "success",
  "imported": 127,
  "skipped": 873,
  "pages": 15,
  "reached_target": true
}

Example:

Call readwise_backfill_highlights(target_date="2026-01-01")

Saves to: 2 Resources/Readwise/Highlights/YYYYMMDD-HHMMSS [Source Title] highlight.md

Filename Format: Highlights are saved with temporal prefix for chronological sorting:

  • 20260130-143020 [Building a Second Brain] highlight.md
  • 20260130-142815 [The Phoenix Project] highlight.md

State File Format

The server maintains state at .claude/state/readwise-import.json:

{
  "last_import_timestamp": "2026-01-22T04:29:12.864733Z",
  "oldest_imported_date": "2026-01-01",
  "synced_ranges": [
    {
      "start": "2026-01-01T06:17:43.693000+00:00",
      "end": "2026-01-21T02:33:27.975000+00:00",
      "doc_count": 614,
      "verified_at": "2026-01-21T10:43:56.626549Z"
    }
  ],
  "backfill_in_progress": false,
  "highlights": {
    "last_import_timestamp": "2026-01-30T05:00:00Z",
    "synced_ranges": [],
    "backfill_in_progress": false
  }
}

Highlights State: The highlights section tracks separate import state for highlights:

  • last_import_timestamp: Last highlights import time
  • synced_ranges: Optimized ranges for highlights backfill
  • backfill_in_progress: Whether a highlights backfill was interrupted

Backward Compatibility: Existing state files without the highlights section will have it automatically created on first use.

Testing

Run the test suite:

source venv/bin/activate
pytest test_server.py -v

Test Categories

Unit Tests:

  • State file reading/writing
  • Synced range optimization logic
  • Filename sanitization
  • ID extraction from URLs
  • Document scanning for deduplication

Integration Tests:

  • API calls with mocked responses
  • Markdown formatting
  • Document saving with collision handling
  • Highlights query tools (daily_review, book_highlights, search_highlights)
  • Highlights import and backfill with deduplication

Troubleshooting

Connection Issues

  1. Check MCP connection:

    /mcp
    

    Should show "Connected to readwise"

  2. Verify environment variables are set correctly in .mcp.json

  3. Check logs in stderr output

State Issues

If state file appears corrupted:

  1. View current state:

    Call readwise_state_info()
    
  2. Reset state (preserve ranges):

    Call readwise_reset_state()
    
  3. Rebuild ranges from filesystem:

    Call readwise_init_ranges()
    

Deduplication Issues

If documents are being imported multiple times:

  1. Rebuild synced ranges:

    Call readwise_init_ranges()
    
  2. Check filesystem for duplicate filenames manually

  3. Verify readwise_url frontmatter is present in existing documents

Architecture

Single-File Design

The server is intentionally kept to a single file (~350 lines) for:

  • Simplicity and maintainability
  • Easy deployment and updates
  • Minimal dependencies
  • Clear code organization

Reused Logic

Key functions reused from .claude/scripts/readwise-backfill.py:

  • load_state() / write_state() - State management
  • optimize_backfill() - Synced range optimization
  • scan_existing_documents() - Filesystem deduplication
  • sanitize_filename() - Safe filename generation
  • extract_id_from_url() - ID extraction

Token Efficiency

Optimizations for reduced token usage:

  • 8 tools vs 13+ in Node.js version (38% reduction)
  • Combined operations (fetch + dedupe + save in one call)
  • Smart defaults minimize required parameters
  • Tool descriptions limited to 20-30 words
  • Returns structured summaries, not full markdown dumps

Estimated token overhead reduction: ~60%

Comparison with Node.js Version

FeaturePython MCPNode.js MCP
Lines of code~1,000~6,749
Tool count1013+
Dependencies410+
State compatibility✓✓
Token efficiencyHighMedium
MaintenanceSimpleComplex
Highlights import✓✗

Development

Running locally for development

source venv/bin/activate
python server.py

Adding new tools

  1. Add tool function using @mcp.tool() decorator
  2. Follow existing patterns for error handling and logging
  3. Return structured dict with status field
  4. Add tests to test_server.py
  5. Update README.md with tool documentation

License

MIT

Credits

  • Built with FastMCP by Anthropic
  • Based on proven logic from .claude/scripts/readwise-backfill.py
  • Designed for token efficiency and simplicity
Ver o original no GitHub

Bom para

Relacionados