🚀 Medium Blog MCP Server

AI-powered blog generation system built with FastMCP. Automates research, content generation, quality checks, and Medium export for technical blog posts.

✨ Features

• 🔍 Multi-Source Research: Automatically gathers content from Wikipedia, arXiv, web search, and images
• 🤖 AI Content Generation: Uses Claude API to generate high-quality blog posts
• 📊 Image Processing: Downloads and describes images with AI-generated descriptions
• 📝 Quality Analysis: Comprehensive readability, citation, and SEO checks
• ✅ Plagiarism Tracking: Hybrid manual/automated plagiarism checking workflow
• 📤 Medium Export: One-click export to Medium-ready markdown format
• 💾 SQLite Storage: Persistent storage of all drafts and research

🏗️ Architecture

Medium Blog MCP Server
├── Research Engine (Wikipedia, arXiv, Web, Images)
├── AI Content Generator (Claude API)
├── Image Handler (Download + AI Description)
├── Quality Analyzer (Readability, Citations, SEO)
├── Medium Exporter (Markdown + Assets)
└── SQLite Database (Sessions, Drafts, Research)

📋 Prerequisites

• Python 3.10+
• Anthropic API Key (Get one here)
• pip or conda

🚀 Quick Start

1. Clone and Install

# Clone repository
git clone <your-repo-url>
cd medium-blog-mcp

# Activate virtual environment
uv init
uv sync

# Install dependencies
uv add -r requirements.txt

# use these uv commands to test , run mcp servers
Test the server - uv run fastmcp dev main.py
Run the server - uv run fastmcp run main.py
Add the server to claude desktop - uv run fastmcp install
claude-desktop main.py

2. Configure Environment

# Copy environment template
cp .env.example .env

# Edit .env and add your DB URL
# DATABASE_URL=YOUR_SQLITE_DB_URL

3. Run the Server

python main.py

The MCP server will start and be available for Claude Desktop or other MCP clients.

🔧 Configuration for Claude Desktop

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "medium-blog-generator": {
      "command": "[Your/Path/to/uv]",
      "args": [
        "--directory",
        "C:\\medium_mcp",
        "run",
        "fastmcp",
        "run",
        "main.py"
      ],
      "env": {},
      "transport": "stdio",
      "type": null,
      "cwd": null,
      "timeout": null,
      "description": null,
      "icon": null,
      "authentication": null
    }
  }
}

Config locations:

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

📖 Complete Workflow

Step 1: Create Session

create_blog_session(topic="Latest AI Model Advancements", target_length="medium")

Step 2: Research Phase ⭐ USER CHECKPOINT

research_topic(session_id="abc123", depth="comprehensive")
get_research_summary(session_id="abc123")  # Review research
approve_research(session_id="abc123")       # Approve to continue

Step 3: Outline Generation ⭐ USER CHECKPOINT

generate_outline(session_id="abc123", style="technical", num_sections=5)
# Review outline, optionally modify
approve_outline(session_id="abc123")

Step 4: Content Generation

generate_full_content(session_id="abc123")
get_full_draft(session_id="abc123")  # Review full draft

Step 5: Plagiarism Checking ⭐ USER CHECKPOINT (Manual)

prepare_plagiarism_chunks(session_id="abc123")
# Copy chunks to Grammarly/QuillBot/GPTZero manually
record_plagiarism_result(session_id="abc123", chunk_id=1, 
                        plagiarism_score=2.3, ai_detection_score=8.5, 
                        tool_used="Grammarly")

Step 6: Quality Analysis ⭐ USER CHECKPOINT

run_quality_analysis(session_id="abc123")  # Get detailed QA report
approve_final_draft(session_id="abc123")   # Final approval

Step 7: Export to Medium

export_to_medium(session_id="abc123")

🛠️ Available MCP Tools

Session Management

• create_blog_session - Start new blog project
• get_session_status - Check progress
• list_sessions - List all sessions

Research

• research_topic - Multi-source research
• get_research_summary - Review findings
• add_custom_source - Add manual sources
• approve_research - ⭐ Proceed to outline

Outline

• generate_outline - AI-generated structure
• modify_outline - Make changes
• approve_outline - ⭐ Proceed to writing

Content Generation

• generate_full_content - Generate blog
• get_full_draft - Review content
• regenerate_section - Improve specific section

Plagiarism Checking

• prepare_plagiarism_chunks - Split for checking
• record_plagiarism_result - ⭐ Record manual checks
• get_plagiarism_summary - View all results

Quality & Export

• run_quality_analysis - Comprehensive QA
• approve_final_draft - ⭐ Final approval
• export_to_medium - Generate export files

📁 Project Structure

medium-blog-mcp/
├── main.py                   # FastMCP server (all tools)
├── database.py               # SQLAlchemy models & DB operations
├── research.py               # Multi-source research engine
├── content_generator.py      # Claude API content generation
├── image_handler.py          # Image download & AI descriptions
├── quality.py                # Quality analysis & readability
├── exporter.py               # Medium markdown export
├── config.py                 # Configuration management
├── requirements.txt          # Python dependencies
├── .env.example              # Environment variables template
├── README.md                 # This file
└── data/                     # Generated data (auto-created)
    ├── blog_database.db      # SQLite database
    ├── sessions/             # Session-specific data
    │   └── {session_id}/
    │       └── images/       # Downloaded images
    ├── exports/              # Final exports
    │   └── {session_id}/
    │       ├── blog_post.md
    │       ├── images/
    │       ├── citations.txt
    │       ├── metadata.json
    │       └── qa_report.txt
    └── images/               # Image storage

🎯 Usage Example

Here's a complete example of generating a blog about AI models:

# 1. Create session
create_blog_session(topic="GPT-4 vs Claude 3: Technical Comparison", target_length="medium")
# Returns: {"session_id": "abc123", ...}

# 2. Research
research_topic(session_id="abc123", depth="comprehensive")
get_research_summary(session_id="abc123")
# Review the 15-20 sources gathered
approve_research(session_id="abc123")

# 3. Generate outline
generate_outline(session_id="abc123", style="technical", num_sections=5)
# Review outline structure
approve_outline(session_id="abc123")

# 4. Generate content
generate_full_content(session_id="abc123")
get_full_draft(session_id="abc123")
# Review the ~2500 word blog with images

# 5. Check plagiarism manually
prepare_plagiarism_chunks(session_id="abc123")
# Copy chunks to Grammarly, check, then:
record_plagiarism_result(session_id="abc123", chunk_id=1, 
                        plagiarism_score=1.8, ai_detection_score=7.2, 
                        tool_used="Grammarly")

# 6. Quality analysis
run_quality_analysis(session_id="abc123")
# Review QA report
approve_final_draft(session_id="abc123")

# 7. Export
export_to_medium(session_id="abc123")
# Get Medium-ready markdown + all assets!

Total time: 30-45 minutes for a complete 2500-word blog!

🔍 Quality Checks

The system automatically checks:

Readability

• Flesch Reading Ease score
• Flesch-Kincaid Grade Level
• Average sentence length
• Passive voice percentage

Citations

• All sources properly cited
• Citation format validation
• Unused sources identified

Images

• All images have descriptions
• Alt text present
• Proper placement

SEO

• Title length (50-70 chars optimal)
• Header hierarchy (H1, H2, H3)
• Keyword presence
• Meta information

Structure

• Word count vs target
• Section balance
• Overall organization

📊 Database Schema

Tables

• sessions - Blog sessions
• research_sources - Research data
• outlines - Generated outlines
• blog_drafts - Blog content versions
• images - Downloaded images
• plagiarism_checks - Manual check results
• quality_checks - QA reports

All data persists across sessions and can be resumed.

🐛 Troubleshooting

Database Issues

# Reset database (WARNING: deletes all data)
rm data/blog_database.db
python main.py  # Will recreate database

Image Download Failures

• Check internet connection
• Some images may be behind authentication
• System will create fallback descriptions

🔄 Development Roadmap

Current Version (v1.0)

• ✅ Multi-source research
• ✅ AI content generation
• ✅ Image processing
• ✅ Quality analysis
• ✅ Medium export

Future Enhancements (v2.0+)

• 🔲 Automated plagiarism APIs
• 🔲 Multiple format exports (HTML, PDF)
• 🔲 Note-taking app integrations (Obsidian, Notion)
• 🔲 Multi-blog management
• 🔲 SEO optimization suggestions
• 🔲 Social media snippet generation

📝 License

MIT License - feel free to use and modify for your needs.

🤝 Contributing

Contributions welcome! Please:

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

💬 Support

For issues or questions:

• Open an issue on GitHub
• Check the documentation
• Review example workflows

🙏 Credits

Built with:

• FastMCP - MCP server framework
• Anthropic Claude - AI content generation
• SQLAlchemy - Database ORM
• Various open-source research APIs

---

Happy blogging! 🚀