Pitthammerit/medium-reader-mcp

Medium Reader MCP Server

A Model Context Protocol (MCP) server that provides authenticated access to Medium articles and bookmarks. Bypass paywalls with your Medium subscription and manage your reading list programmatically. Works only if you have a payed subscription to medium.

Features

• Authenticated Article Reading: Access any Medium article with your subscription (bypasses paywalls)
• Bookmark Management: List, search, and access your saved articles
• Smart Session Management: Auto-login and re-authentication on expiration
• Multiple Formats: Get articles in Markdown or plain text
• Fast Performance: In-memory cookie caching for sub-second responses

Quick Start

1. Installation

cd /Users/benjaminkurtz/Documents/*localcoding/medium-reader-mcp
npm install
npm run build

2. Configuration

Copy the example environment file and add your credentials:

cp .env.example .env

Edit .env and add your Medium credentials:

# Option 1: Email/Password (Recommended)
MEDIUM_EMAIL=your-email@example.com
MEDIUM_PASSWORD=your-password

# Option 2: Manual Cookies (if login fails)
# MEDIUM_UID=your-uid-cookie
# MEDIUM_SID=your-sid-cookie

Getting Manual Cookies (if needed):

1. Login to Medium in your browser
2. Open Developer Tools (F12)
3. Go to Application > Cookies > https://medium.com
4. Copy the values of uid and sid cookies

3. Add to Claude Code

Add this configuration to your ~/.claude/mcp.json:

{
  "mcpServers": {
    "medium-reader": {
      "command": "node",
      "args": ["/Users/benjaminkurtz/Documents/*localcoding/medium-reader-mcp/dist/index.js"],
      "env": {
        "MEDIUM_EMAIL": "${MEDIUM_EMAIL}",
        "MEDIUM_PASSWORD": "${MEDIUM_PASSWORD}"
      }
    }
  }
}

Note: Make sure you have MEDIUM_EMAIL and MEDIUM_PASSWORD set in your shell environment, or replace ${MEDIUM_EMAIL} with your actual credentials (not recommended for security).

4. Restart Claude Code

Restart Claude Code to load the new MCP server.

Usage

Read a Medium Article

Read this Medium article: https://medium.com/@author/article-title-123abc

Claude will use the read_medium_article tool to fetch and display the article content.

Get Latest Bookmark

Show me my latest Medium bookmark

Uses get_latest_bookmark to retrieve your most recently saved article.

List Bookmarks

List my Medium bookmarks

Show me 10 bookmarks starting from the 5th one

Uses list_bookmarks with optional pagination.

Search Bookmarks

Search my Medium bookmarks for "machine learning"

Uses search_bookmarks to find relevant articles.

MCP Tools

read_medium_article

Read a Medium article with authentication.

Input:

{
  url: string,          // Required: Full Medium article URL
  format?: "markdown" | "text"  // Optional: Output format (default: markdown)
}

Output:

{
  title: string,
  author: string,
  date: string,         // ISO 8601 format
  content: string,      // Article content in requested format
  tags: string[],
  claps: number,
  url: string
}

get_latest_bookmark

Get your most recently bookmarked article.

Input:

{
  autoRead?: boolean    // Optional: Auto-read full content (default: true)
}

Output: Same as read_medium_article

list_bookmarks

List your Medium bookmarks with pagination.

Input:

{
  limit?: number,       // Optional: Max bookmarks to return
  offset?: number       // Optional: Skip N bookmarks (pagination)
}

Output:

{
  bookmarks: Array<{
    title: string,
    url: string,
    author: string,
    date: string,
    preview: string     // First ~200 characters
  }>,
  total: number,
  hasMore: boolean
}

search_bookmarks

Search your bookmarks by keyword.

Input:

{
  query: string,        // Required: Search query
  limit?: number        // Optional: Max results
}

Output: Same as list_bookmarks, but filtered and ranked by relevance

Architecture

src/
├── index.ts              # MCP server entry point
├── config.ts             # Environment configuration
├── types.ts              # TypeScript type definitions
├── medium-client.ts      # Authenticated HTTP client
├── auth/
│   ├── medium-auth.ts    # Email/password authentication
│   ├── session-manager.ts # Cookie caching & auto-refresh
│   └── cookie-parser.ts  # Cookie utilities
├── parsers/
│   ├── article.ts        # Extract article content
│   ├── bookmarks.ts      # Parse bookmarks page
│   └── markdown.ts       # HTML to Markdown conversion
└── tools/
    ├── read-article.ts   # read_medium_article tool
    ├── latest-bookmark.ts # get_latest_bookmark tool
    ├── list-bookmarks.ts # list_bookmarks tool
    └── search-bookmarks.ts # search_bookmarks tool

Performance

• First request (with login): <3 seconds
• Cached session: <1 second
• Bookmark operations: <4 seconds
• Session cache: 1 hour TTL with auto-refresh
• Bookmarks cache: 5 minutes TTL

Security

• Credentials are never logged
• Session cookies cached in memory only (not persisted)
• Auto re-authentication on session expiration
• Environment variables for credential management
• .env file excluded from version control

Troubleshooting

See for common issues and solutions.

Development

Build

npm run build

Watch Mode

npm run watch

Type Check

npm run type-check

License

ISC