Instapaper MCP Server

A comprehensive Model Context Protocol (MCP) server for Instapaper integration. This server allows Claude and other MCP clients to interact with your Instapaper account - reading, saving, organizing, and analyzing your articles.

Like what you see?

Buy me a coffee: https://cmdzed.com/#/portal/support

Features

🛠️ Tools (Actions)

Content Management:

• add_bookmark - Save articles with title, description, and folder

• add_private_bookmark - Save private content without URLs (emails, notes, generated content)

• delete_bookmark - Remove articles

• archive_bookmark - Move articles to archive

• unarchive_bookmark - Restore from archive

• star_bookmark - Mark as important

• unstar_bookmark - Remove star

• move_bookmark - Organize into folders

• update_read_progress - Track reading progress

Bulk Operations (Parallel Processing):

• move_bookmarks_bulk - Move multiple bookmarks to a folder at once

• star_bookmarks_bulk - Star multiple bookmarks in parallel

• unstar_bookmarks_bulk - Remove stars from multiple bookmarks

• archive_bookmarks_bulk - Archive multiple bookmarks at once

• unarchive_bookmarks_bulk - Restore multiple bookmarks from archive

• update_read_progress_bulk - Update reading progress for multiple articles

Folder Management:

• list_folders - View all folders

• create_folder - Create new folders

• delete_folder - Remove folders

• reorder_folders - Customize folder order

Highlights:

• add_highlight - Save important passages

• list_highlights - View highlights for an article

• delete_highlight - Remove highlights

Search & Discovery:

• list_bookmarks - List articles from folders with sync support

• search_bookmarks - Find articles by title, URL, or description

Content Access:

• get_article_content - Fetch full text of a single article

• get_articles_content_bulk - Fetch content from multiple articles at once for bulk analysis

📚 Resources (Data Claude Can Read)

• instapaper://bookmarks/unread - All unread articles

• instapaper://bookmarks/archive - Archived articles

• instapaper://bookmarks/starred - Starred articles

• instapaper://folders - List of folders

• instapaper://folder/{folder_id} - Articles in a specific folder

• instapaper://article/{bookmark_id} - Full text of an article

💡 Prompts (Reusable Workflows)

• weekly_reading_digest - Organized summary of unread articles

• recommend_next_read - AI-powered reading suggestions

• research_synthesis - Synthesize insights from articles on a topic

• organize_backlog - Suggest folder organization

• archive_candidates - Identify old articles to archive

• save_as_private_bookmark - Guidelines for saving private content and generated insights

Installation

Prerequisites

1. Node.js 18+ installed on your system

2. Instapaper account with API credentials

Step 1: Get Instapaper API Credentials

1. Go to https://www.instapaper.com/api

2. Fill out the API access request form

3. Wait for approval (usually takes a few days)

4. You'll receive a Consumer Key and Consumer Secret

Step 2: Clone and Install

Step 3: Configure Environment Variables

Edit .env and add your credentials:

Step 4: Build the Server

Usage with Claude Desktop

Configure Claude Desktop

Add this to your Claude Desktop configuration file:

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

Important: Replace /absolute/path/to/instapaper-mcp-server with the actual full path.

Restart Claude Desktop

After updating the config, restart Claude Desktop completely (quit and reopen).

Example Usage

Once configured, you can interact with Instapaper through Claude. Here are real-world examples showing what happens when you make requests:

Example 1: Organize Recent Bookmarks by Topic

You ask Claude:

Claude's workflow:

1. Fetches your unread bookmarks using list_bookmarks

2. Analyzes the titles and URLs to identify topics (e.g., "AI/ML", "Design", "Product Management")

3. Creates new folders for each topic using create_folder

4. Gets the bookmark IDs for articles in each category

5. Uses move_bookmarks_bulk to organize them all at once

You see:

Example 2: Review Top Articles and Sync Across Devices

You ask Claude:

Claude's workflow:

1. Fetches starred bookmarks using list_bookmarks with folder: "starred"

2. Retrieves full article text for your starred items using get_articles_content_bulk

3. Analyzes the content and identifies the most compelling articles

4. Updates reading progress for selected articles using update_read_progress_bulk

You see:

Example 3: Batch Process and Archive

You ask Claude:

Claude's workflow:

1. Lists all unread bookmarks with timestamps

2. Filters for articles older than 3 months

3. Excludes any that are starred

4. Uses archive_bookmarks_bulk to move them all to archive

You see:

Example 4: Research Synthesis

You ask Claude:

Claude's workflow:

1. Searches bookmarks using search_bookmarks for "remote work culture"

2. Fetches full article content using get_articles_content_bulk

3. Synthesizes key insights from all articles

4. Optionally stars the most relevant articles using star_bookmarks_bulk

You see:

Example 5: Quick Content Pipeline

You ask Claude:

Claude's workflow:

1. Saves article using add_bookmark to specified folder

2. Confirms save is complete

You see:

Development

Run in Development Mode

Project Structure

Troubleshooting

Authentication Errors

If you see authentication errors:

1. Verify your credentials in .env

2. Ensure you have API access (check your Instapaper email)

3. Try re-authenticating by restarting Claude Desktop

Tools Not Showing Up

1. Check that the path in claude_desktop_config.json is absolute

2. Verify the server builds successfully: npm run build

3. Check Claude Desktop logs for errors

API Rate Limits

Instapaper has rate limits. If you hit them:

• Wait a few minutes before trying again

• Reduce the frequency of requests

• Use resources (reading data) instead of tools when possible

Advanced Features

Reading Full Article Text

Claude will use the instapaper://article/{bookmark_id} resource to access the full article content.

Folder-Based Research

Highlight Management

Bulk Operations

Bulk Content Analysis:

Bulk Organization:

Bulk Status Updates:

All bulk operations execute requests in parallel for maximum efficiency and return detailed results including success count, failure count, and per-item status.

Integration Ideas

With Your Ghost Blog

Since you run a blog, you could:

1. Research articles from Instapaper

2. Have Claude synthesize insights

3. Draft blog posts informed by your reading

4. Save drafts back to Instapaper for review on Kindle

For UX Research

1. Save research articles to specific folders

2. Use prompts to synthesize findings

3. Track reading progress on long reports

4. Highlight key insights for later reference

Security Notes

• Your .env file contains sensitive credentials - never commit it to git

• The .gitignore file is configured to exclude .env

• API credentials are stored locally on your machine

• Claude Desktop launches the server locally - nothing is sent to external servers except Instapaper's official API

License

MIT

Contributing

Contributions welcome! Please feel free to submit issues or pull requests.

Resources

• Instapaper API Documentation

• Model Context Protocol Specification

• MCP TypeScript SDK

Changelog

v1.2.0 (Latest)

• Added 5 new bulk operation tools with parallel processing:

  • star_bookmarks_bulk - Star multiple bookmarks at once

  • unstar_bookmarks_bulk - Remove stars from multiple bookmarks

  • archive_bookmarks_bulk - Archive multiple bookmarks in parallel

  • unarchive_bookmarks_bulk - Restore multiple bookmarks from archive

  • update_read_progress_bulk - Update progress for multiple articles

• Added list_bookmarks tool with advanced filtering and sync support

• Added reorder_folders tool for custom folder organization

• Enhanced bulk operation documentation with examples

• All bulk tools provide detailed success/failure statistics

v1.1.0

• Added get_article_content tool for fetching individual article text

• Added get_articles_content_bulk tool for bulk article content retrieval

• Enhanced parallel processing for better performance

• Improved error handling in bulk operations

v1.0.0

• Initial release

• Complete implementation of Instapaper API

• All tools, resources, and prompts

• OAuth 1.0 authentication

• Comprehensive error handling