tsheiner/medium-mcp-server

Medium MCP Server for Book Writing

Transform your Medium article archive into an intelligent writing assistant using Claude Desktop and the Model Context Protocol (MCP).

What This Does

This MCP server gives Claude Desktop deep access to your Medium article collection, enabling sophisticated analysis and writing support for authors looking to:

• Structure a book from existing Medium essays
• Find related content across your writing to combine or reference
• Analyze themes and concepts in your work
• Identify content gaps and writing opportunities
• Organize chapters by topic, complexity, or narrative flow
• Merge multiple essay drafts into cohesive chapters

Perfect for authors who have been writing on Medium and want to transform their distributed thoughts into a structured book.

Features

Core Writing Tools

• find_related_chapters - Find essays with similar themes for combination or reference
• analyze_chapter_completeness - Track which pieces are finished vs drafts vs comments
• get_chapter_content - Access full essay content for editing and review
• extract_design_philosophy - Map recurring themes across your body of work
• identify_content_overlaps - Find redundant or complementary material between essays
• suggest_book_structure - Generate potential chapter sequences and organization

Intelligent Analysis

• Automatically categorizes essays as finished chapters, drafts, or comment responses
• Extracts key concepts and themes from your writing
• Finds content overlaps to help merge related essays
• Suggests book organization by theme, complexity, or workflow
• Tracks writing patterns and recurring ideas

Prerequisites

1. Medium Article Export: You need your Medium articles in a specific directory structure with images downloaded locally. See link below to downloader script.
2. Claude Desktop: The MCP client for accessing the tools
3. Python 3.8+: To run the MCP server

Getting Your Medium Data

This server requires your Medium articles in a specific format with locally downloaded images. Use the companion repository to prepare your data:

Medium Archive Image Downloader

That tool processes Medium's bulk export to:

• Download all referenced images locally
• Update HTML files to use local image paths
• Organize articles in the required directory structure

Installation

1. Clone and Setup

git clone <this-repo>
cd medium_mcp_server

2. Create Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Prepare Your Data

Place your processed Medium archive in the data/ directory. The structure should look like:

data/
├── Article-Title-1-abc123/
│   ├── Article-Title-1-abc123.html
│   └── img/
│       ├── image1.jpg
│       └── image2.png
├── Article-Title-2-def456/
│   ├── Article-Title-2-def456.html
│   └── img/
└── ...

5. Configure Finished Essays

Edit src/book_server.py and update the FINISHED_CHAPTERS set with the directory names of your completed essays:

FINISHED_CHAPTERS = {
    "Your-Finished-Essay-1-abc123",
    "Another-Complete-Article-def456",
    # Add your finished essay directory names here
}

6. Test the Server

python src/book_server.py

If successful, the server will start and show how many chapters it indexed (e.g., "Successfully indexed 46 chapters").

Claude Desktop Integration

1. Find Your Claude Desktop Config

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

2. Add the MCP Server

Add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "medium-book-mcp-server": {
      "command": "/path/to/your/venv/bin/python3",
      "args": ["/path/to/medium_mcp_server/src/book_server.py"],
      "env": {}
    }
  }
}

Important: Use the full path to your virtual environment's Python executable. Find it with:

# In your activated venv:
which python3

3. Restart Claude Desktop

Completely quit and restart Claude Desktop to load the new server.

Usage Examples

Once configured, you can ask Claude questions like:

Content Discovery

• "What themes do I write about most frequently?"
• "Show me all my essays about user experience"
• "Which of my articles are substantial enough to be book chapters?"

Book Structure Planning

• "Help me organize my finished essays into a logical book structure"
• "What would make good opening vs closing chapters?"
• "Group my essays by theme for potential book sections"

Content Combination

• "I have multiple drafts about design systems - help me see how to combine them"
• "Find essays that overlap in content so I can merge them"
• "Which articles complement each other and should be sequential chapters?"

Writing Strategy

• "What design concepts am I missing from my collection?"
• "Identify patterns in my most successful pieces"
• "What topics do I keep returning to?"

Customization

Adding Your Own Concepts

Edit the extract_design_concepts() function in src/book_server.py to include terminology specific to your domain:

design_terms = [
    'your domain term 1',
    'your domain term 2', 
    # Add concepts relevant to your writing
]

Adjusting Chapter Status

The server automatically categorizes essays, but you can fine-tune the logic in extract_chapter_content() based on your writing patterns.

Troubleshooting

Server Won't Start

• Check that your virtual environment is activated and has all dependencies
• Ensure the data/ directory exists and contains your Medium articles
• Look at Claude Desktop's MCP logs for specific error messages

No Articles Found

• Verify your data directory structure matches the expected format
• Check that HTML files are directly inside article directories
• Run the server manually to see indexing output

Missing Dependencies

• Make sure you're using the virtual environment's Python in the Claude config
• Reinstall requirements with pip install -r requirements.txt

Contributing

This tool is designed to be extensible. Potential enhancements:

• More sophisticated content analysis
• Export functions for book outlines
• Integration with writing tools
• Enhanced theme extraction
• Collaborative writing features

License

MIT License - Use this to build your book!

Related Projects

• Medium Archive Image Downloader - Prepare your Medium export for this tool
• Model Context Protocol - The protocol that powers Claude integrations