Medium Local MCP Server

A local Model Context Protocol (MCP) server specifically optimized for LLMs to fetch and process Medium.com articles. This server handles authentication, rate limiting, and provides structured, LLM-friendly output.

Features

• LLM-Optimized Content Extraction: Structured output with metadata, sections, code blocks, and knowledge extraction
• Subscription Authentication: Respects your Medium subscription to access subscriber-only content
• Rate Limiting: Built-in rate limiting to avoid 403 errors and respect Medium's limits
• Local Processing: All processing happens locally for privacy
• Code Preservation: Maintains code blocks with language detection and context
• Workflow Extraction: Identifies and extracts step-by-step guides and tutorials
• Knowledge Graph Generation: Extracts concepts, technologies, and relationships
• Research-Grade Citations: Handles academic and technical references

Prerequisites

• Node.js 18+
• npm
• Chrome/Chromium browser (for authentication)
• Medium subscription (for accessing subscriber content)

Installation

Via Universal MCP Setup Script

The easiest way to install is using the universal MCP setup script:

./universal-mcp-setup.sh
# Select option 35) Medium Local

Manual Installation

1. Install dependencies:

npm install

2. Build the TypeScript:

npm run build

3. Add to Claude MCP settings:

claude mcp add-json "medium-local" '{
  "type": "stdio",
  "command": "node",
  "args": ["./dist/index.js"],
  "env": {
    "MEDIUM_COOKIE_PATH": "~/.medium-mcp/cookies.json",
    "RATE_LIMIT_MS": "3000",
    "HEADLESS": "true"
  }
}' -s user

Authentication

First-time Setup

1. Login to Medium:

medium-auth login

This will open a browser window where you can log into Medium. The browser will close automatically after successful login.

2. Check authentication status:

medium-auth status

3. Refresh session (if needed):

medium-auth refresh

4. Logout:

medium-auth logout

Available MCP Tools

fetch_article_structured

Fetch and process a Medium article with comprehensive LLM optimization.

Parameters:

• url (required): Medium article URL
• extractCode (optional): Extract code blocks with context
• extractWorkflows (optional): Extract step-by-step workflows
• extractConcepts (optional): Extract technical concepts
• generateSummary (optional): Generate AI summary
• includeComments (optional): Include valuable comments

Output Structure:

{
  "metadata": {
    "title": "Article Title",
    "author": "Author Name",
    "publishDate": "2025-01-12",
    "readingTime": 8,
    "tags": ["react", "javascript"],
    "claps": 1500,
    "url": "https://medium.com/..."
  },
  "content": {
    "markdown": "Full article in Markdown",
    "structured": {
      "sections": [...],
      "codeBlocks": [...],
      "keyPoints": [...],
      "links": [...],
      "images": [...]
    },
    "summary": "AI-generated summary",
    "tldr": ["Key point 1", "Key point 2", ...]
  },
  "knowledge": {
    "concepts": [...],
    "technologies": [...],
    "workflows": [...],
    "solutions": [...],
    "definitions": [...]
  },
  "research": {
    "citations": [...],
    "relatedArticles": [...],
    "updates": [...],
    "comparisons": [...]
  }
}

research_topic

Research a topic on Medium with advanced filtering.

Parameters:

• query (required): Search query
• minClaps (optional): Minimum claps filter
• tags (optional): Filter by tags
• authors (optional): Filter by authors
• publications (optional): Filter by publications
• limit (optional): Maximum results (default: 10)
• extractionDepth (optional): "shallow" or "deep" (default: "shallow")

fetch_series

Fetch all articles in a Medium series.

Parameters:

• seriesUrl (required): Medium series URL
• orderBy (optional): "chronological" or "relevance" (default: "chronological")

extract_user_highlights

Extract your saved highlights from Medium articles.

get_reading_list

Get your Medium reading list.

Configuration

Environment variables:

• MEDIUM_COOKIE_PATH: Path to store authentication cookies (default: ~/.medium-mcp/cookies.json)
• RATE_LIMIT_MS: Rate limiting delay in milliseconds (default: 3000)
• HEADLESS: Run browser in headless mode (default: true)
• LOG_LEVEL: Logging level (default: info)

Usage Examples

Fetch a Technical Article

// In Claude, use the fetch_article_structured tool
{
  "url": "https://medium.com/@author/react-performance-optimization-guide",
  "extractCode": true,
  "extractWorkflows": true,
  "extractConcepts": true,
  "generateSummary": true
}

Research AI/ML Topics

// Research recent AI articles
{
  "query": "machine learning optimization",
  "minClaps": 100,
  "tags": ["artificial-intelligence", "machine-learning"],
  "limit": 5,
  "extractionDepth": "deep"
}

Get a Complete Tutorial Series

// Fetch entire tutorial series
{
  "seriesUrl": "https://medium.com/@author/react-mastery-series",
  "orderBy": "chronological"
}

Privacy & Security

• All processing happens locally on your machine
• No data is sent to external APIs (except Medium.com)
• Authentication cookies are stored locally and encrypted
• Rate limiting respects Medium's terms of service

Troubleshooting

Authentication Issues

# Check if authenticated
medium-auth status

# Refresh session
medium-auth refresh

# Re-login if needed
medium-auth logout
medium-auth login

Rate Limiting

The server automatically handles rate limiting. If you encounter 403 errors:

• Increase RATE_LIMIT_MS environment variable
• The server will automatically back off and retry

Build Issues

# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build

Development

Project Structure

src/
├── index.ts           # Main MCP server
├── auth/
│   └── manager.ts     # Authentication management
├── fetcher/
│   ├── playwright.ts  # Browser automation
│   └── rateLimit.ts   # Rate limiting
├── parser/
│   └── processor.ts   # Content processing
├── types/
│   └── index.ts       # TypeScript definitions
└── utils/
    └── logger.ts      # Logging utilities

Running in Development

npm run dev

Testing

npm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License