Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@reading-companion Interview me for my reading goals"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A 4-stage reading companion that helps you set goals, discover books, track progress, and deepen learning through reflection.
Works as an MCP (Model Context Protocol) server integrated with Claude Desktop.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ STAGE 1 │ │ STAGE 2 │ │ STAGE 3 │
│ Interviewer │ ──▶ │ Context │ ──▶ │ Syllabus │
│ │ │ Builder │ │ Builder │
│ "Who are you │ │ "Extract │ │ "Build your │
│ as a reader"│ │ patterns" │ │ book stacks"│
└──────────────┘ └──────────────┘ └──────────────┘
│ │
│ ┌──────────────┐ │
└────────────▶ │ STAGE 4 │ ◀──────────┘
│ Reflection │
│ Partner │
│ │
│ "What did │
│ you learn?" │
└──────────────┘Interviewer - Builds your reading profile through conversation
Context Builder - Extracts deeper patterns from your profile
Syllabus Builder - Creates curated book stacks for each domain
Reflection Partner - Helps process books and track growth
Related MCP server: Readbook MCP Server
Python 3.10+
uv (Python package manager)
Claude Desktop
# Clone the repo
git clone https://github.com/aby0/reading-companion
cd reading-companion
# Install dependencies
uv syncAdd to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"reading-companion": {
"command": "uv",
"args": ["--directory", "/path/to/reading-companion", "run", "reading-companion"]
}
}
}Replace /path/to/reading-companion with the actual path where you cloned the repo.
Restart Claude Desktop. You should see "Reading Companion" in the MCP servers list (hammer icon).
Step 1: Run the Interview
You: "Interview me for my reading goals"Claude will ask about your goals, preferences, and context. At the end, your profile is saved.
Step 2: Extract Context (Optional)
You: "Analyze my reading profile"Claude extracts deeper patterns to improve recommendations.
Step 3: Build Your Book Stacks
You: "Build me a reading stack for classic literature"Get curated book recommendations for each domain.
Log a completed book:
You: "I just finished Anna Karenina by Tolstoy"Reflect on a book:
You: "I want to reflect on Anna Karenina"Check progress:
You: "How's my reading progress?"Get next recommendation:
You: "What should I read next?"Add a book manually:
You: "Add 'War and Peace' to my classic lit stack"Tool | Description |
| Begin the reading goal interview |
| Save interview results as profile |
| View current profile |
Tool | Description |
| Analyze profile for deeper patterns |
| Save extracted features |
Tool | Description |
| Generate recommendations for a domain |
| Save generated book stack |
| View all book stacks |
| Get next unread book |
| Manually add a book |
Tool | Description |
| Quick log a completed book |
| Begin deep reflection session |
| Save reflection insights |
| View reading history |
| Get progress summary |
Tool | Description |
| Analyze your reading history for patterns |
| View profile for an author you've read |
| Add style notes about an author |
| List your top authors by affinity |
| Link related books together |
| Find books connected to one you've read |
All your reading data is stored in ~/reading-companion-data/ (separate from the code):
~/reading-companion-data/
├── profile.md # Your profile (human-readable)
├── profile.json # Profile data (system)
├── bookstacks.json # All stacks data (system)
├── authors.json # Author tracking (system)
├── patterns.json # Reading patterns (system)
├── connections.json # Book connections (system)
│
├── bookstacks/ # Book recommendations
│ ├── _index.md # Overview of all stacks
│ ├── classic_lit.md # One file per domain
│ └── neuroscience.md
│
├── progress/ # Progress tracking
│ ├── _current.md # Current status with progress bars
│ ├── _insights.md # Reading pattern insights
│ └── reading_log.json # Structured log (system)
│
├── authors/ # Author profiles
│ ├── _index.md # All authors by affinity
│ ├── leo-tolstoy.md # One file per author
│ └── james-clear.md
│
└── reflections/ # Book reflections
├── _index.md # Index of all books read
├── anna-karenina.md # One file per book
└── atomic-habits.mdKey feature: All .md files are human-readable and can be opened in VS Code, Obsidian, or any text editor.
The prompts that guide each stage are in the reading_companion/prompts/ directory:
interviewer.md - How interviews are conducted
context_builder.md - How profiles are analyzed
syllabus_builder.md - How books are curated
reflection.md - How reflections are guided
Feel free to customize these to match your preferences.
You can have any reading domains you want - they're not hardcoded. During the interview, define whatever areas interest you:
Classic Literature
Science Fiction
Neuroscience
Philosophy
Engineering
History
Whatever you're curious about!
Intentional over random - Every book serves a purpose
Learning over consuming - Reflection matters as much as reading
Progress over perfection - Steady beats ambitious
Personal over popular - What fits YOU, not bestseller lists
"Reading Companion not appearing in Claude Desktop"
Check that the path in claude_desktop_config.json is correct
Restart Claude Desktop
Check the MCP logs for errors
"No profile found"
Run start_interview first to create your profile
"Domain not found"
Check your domain ID matches what's in your profile
Use get_profile to see available domains
To run the server directly for testing:
uv run reading-companionTo test with the MCP inspector:
npx @modelcontextprotocol/inspector uv run reading-companionMIT
Add a connection between two books for future recommendations.
Args: from_book: Title of the first book to_book: Title of the second book relationship: Type of connection: - "similar_theme": Similar themes or topics - "complements": Different angles on same topic - "next_step": Natural progression from first to second - "contrast": Interesting contrast/counterpoint reason: Why these books are connected strength: "strong" | "moderate" | "weak"
Inputs: from_book (required), to_book (required), relationship (required), reason (required), +1 more.
Manually add a book to an existing stack.
Inputs: domain (required), title (required), author (required), why, +1 more.
Analyze your reading history to identify patterns.
Examines your completed books to find:
Themes you gravitate toward
Difficulty levels that work best
Reading pace insights
Author preferences
Results are saved and used for smarter recommendations.
Inputs: no named parameters.
Build a curated reading stack for a specific domain.
Args: domain: The domain ID to build a stack for (e.g., "classic_lit").
Returns the syllabus builder prompt with user context. After generating recommendations, call save_bookstack to persist them.
Inputs: domain (required).
Analyze the profile to extract latent features.
Returns the context builder prompt along with the current profile. After analysis, call update_latent_features with the results.
Inputs: no named parameters.
Get or create a profile for an author.
Args: author: Author name (e.g., "Leo Tolstoy")
Returns author data including books read, ratings, and notes.
Inputs: author (required).
Get all book stacks, or a specific domain's stack.
Inputs: domain.
Get your favorite authors ranked by affinity.
Args: limit: Maximum number of authors to return (default 10)
Inputs: limit.
Get the next recommended book to read.
Inputs: domain.
Retrieve the current user profile.
Inputs: no named parameters.
Get reading progress summary across all domains.
Inputs: period.
Get reading log entries.
Inputs: limit.
Find books connected to one you've read.
Args: title: Title of a book you've read
Returns books that are connected to this one.
Inputs: title (required).
Log a completed book (quick mode).
Args: title: Book title author: Author name domain: Which domain this book belongs to rating: Optional 1-5 rating quick_note: Optional brief note
Inputs: title (required), author (required), domain (required), rating, +1 more.
Save a curated book stack for a domain.
Args: domain: The domain ID this stack belongs to books: List of book recommendations description: Optional description of what this stack will achieve
Inputs: domain (required), books (required), description.
Save the user's reading profile after the interview.
Args: name: User's name
domains: List of reading domains with goals. Each domain should have:
- id: Short identifier (e.g., "classic_lit", "neuroscience")
- name: Display name (e.g., "Classic Literature")
- purpose: Why they want to read in this area
- target_books: Number of books they aim to read
preferences: Reading preferences dictionary:
- pacing: "slow_deep" | "steady" | "fast_volume"
- challenge_tolerance: "low" | "medium" | "high"
- parallel_books: Number of books they read at once
context: Current context dictionary:
- mood: Current reading mood
- avoidances: List of things to avoidReturns: Confirmation with status and message
Inputs: name (required), domains (required), preferences (required), context (required).
Save a deep reflection for a book.
Args: title: Book title key_takeaway: One sentence distillation craft_lessons: What you learned about writing/craft personal_insights: How this connects to your life favorite_quotes: Memorable passages next_appetite: "more_like_this" | "ready_for_challenge" | "palette_cleanser"
Inputs: title (required), key_takeaway (required), craft_lessons, personal_insights, +2 more.
Begin the reading goal interview.
Returns the interview prompt to guide the conversation. Use this when the user says "interview me" or "set up my profile".
Inputs: no named parameters. Returns: result
Start a deep reflection session for a book.
Inputs: title (required).
Update notes about an author's style and your impressions.
Args: author: Author name style_notes: Dictionary with keys like: - prose: Description of writing style - themes: List of common themes - strengths: What they do well - comparable_to: Similar authors your_notes: Your personal notes about this author
Inputs: author (required), style_notes, your_notes.
Update the profile with extracted latent features.
Args: features: Dictionary of latent features extracted from analysis.
Inputs: features (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 21 tools
Tools have distinct purposes, though some like get_next_book and get_similar_books could be confused; descriptions help resolve ambiguity.
All tools follow a consistent verb_noun pattern with underscores, making them predictable and easy to understand.
21 tools is on the higher side for typical MCP servers, but each serves a unique function in the reading companion domain without redundancy.
Covers core CRUD for profiles, stacks, connections, and reflections, but lacks update/delete for some entities and a book search feature.
Speed-read web pages, books and Claude's answers one word at a time, right in the chat.
A second brain for Claude: remembers your work, plans your day, encrypted under a key only you hold.
AI-powered corporate learning platform — manage courses, users, and insights via Claude.
Search and read the Claude Platform documentation and API reference.
