Medium MCP Server

Version 2.0.0 - Production-ready MCP server for Medium API integration

Overview

Medium MCP (Model Context Protocol) server enables AI assistants to interact with Medium's content platform programmatically. Publish, update, delete articles, manage drafts, and more - all through a unified MCP interface with robust error handling and automatic retries.

🎯 Key Features

• ✅ Complete CRUD Operations - Publish, update, delete, and retrieve articles

• ✅ OAuth 2.0 Authentication - Secure token management with automatic refresh

• ✅ Smart Retry Logic - Exponential backoff for failed requests

• ✅ Rate Limit Handling - Automatic detection and waiting

• ✅ Draft Management - Create, retrieve, and manage drafts

• ✅ User Profile Access - Get user information and publications

• ✅ Search Functionality - Find articles by keywords and tags

• ✅ Type Safety - Full TypeScript support with validation

• ✅ Comprehensive Tests - Jest test suite with 92% coverage

🛠️ Technology Stack

• TypeScript - Type-safe development

• Model Context Protocol (MCP) - AI assistant integration

• Axios - HTTP client with interceptors

• Zod - Schema validation

• Jest - Testing framework

🚀 Quick Start

Prerequisites

• Node.js v16 or later

• npm or yarn

• Medium account

Installation

# 1. Clone the repository
git clone https://github.com/aliiqbal208/medium-mcp.git
cd medium-mcp-server

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env

# 4. Get your Medium integration token
# Visit: https://medium.com/me/settings/security
# Scroll to "Integration tokens" → Enter description → Click "Get integration token"
# Add to .env as: MEDIUM_ACCESS_TOKEN=your_token_here

# 5. Build the project
npm run build

# 6. Run the server
npm start

Development Mode

npm run dev  # Hot reload enabled

Run Tests

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # With coverage report

📚 Available Tools

Article Management

publish-article

Publish a new article on Medium.

Parameters:

• title (string, required): Article title

• content (string, required): Article content in Markdown format

• tags (string[], optional): Up to 5 tags

• publishStatus ('public' | 'draft' | 'unlisted', optional): Publication status (default: 'draft')

• publicationId (string, optional): Publish to a specific publication

• notifyFollowers (boolean, optional): Notify followers when publishing

Example:

{
  "title": "Getting Started with AI",
  "content": "# Introduction\n\nThis is my article about AI...",
  "tags": ["ai", "machine-learning", "tech"],
  "publishStatus": "public"
}

update-article

Update an existing article.

Parameters:

• articleId (string, required): ID of the article to update

• title (string, optional): New title

• content (string, optional): New content

• tags (string[], optional): New tags

• publishStatus ('public' | 'draft' | 'unlisted', optional): New status

delete-article

Delete an article or draft.

Parameters:

• articleId (string, required): ID of the article to delete

get-article

Get details of a specific article.

Parameters:

• articleId (string, required): ID of the article

User & Profile

get-user-profile

Retrieve authenticated user's profile information.

Returns: User ID, username, name, URL, and image URL.

get-drafts

Retrieve all draft articles for the authenticated user.

get-publications

Retrieve all publications the user contributes to.

Search

search-articles

Search and filter Medium articles.

Parameters:

• keywords (string[], optional): Search keywords

• publicationId (string, optional): Filter by publication

• tags (string[], optional): Filter by tags

🔧 Development

Run in Development Mode

npm run dev

Run Tests

npm test

Build the Project

npm run build

🏗️ Architecture

medium-mcp-server/
├── src/
│   ├── index.ts       # MCP server and tool registration (8 tools)
│   ├── auth.ts        # OAuth 2.0 & token management with refresh
│   └── client.ts      # API client with retry logic & rate limiting
├── tests/
│   ├── auth.test.ts   # Authentication tests
│   └── client.test.ts # API client tests
├── .env.example       # Environment configuration template
├── .gitignore         # Git ignore rules
├── tsconfig.json      # TypeScript configuration
├── jest.config.js     # Test configuration
└── package.json       # Dependencies and scripts

🔒 Authentication

Option 1: Integration Token (Recommended)

1. Visit Medium Settings - Security

2. Scroll to "Integration tokens"

3. Enter description: "MCP Server"

4. Click "Get integration token"

5. Add to .env: MEDIUM_ACCESS_TOKEN=your_token_here

Option 2: OAuth (For Applications)

1. Register at Medium Developers

2. Get Client ID and Client Secret

3. Add to .env:

   MEDIUM_CLIENT_ID=your_client_id
   MEDIUM_CLIENT_SECRET=your_client_secret
   MEDIUM_AUTH_CODE=authorization_code

⚡ Features in Detail

Error Handling

• Exponential Backoff: Automatic retry with 1s → 2s → 4s delays

• Rate Limit Detection: Monitors API limits and waits automatically

• Detailed Error Messages: Clear error info with status codes

Token Management

• Persistent Storage: Tokens saved in .medium-tokens.json

• Auto Refresh: Expired tokens refreshed automatically

• Security: Token files excluded from git

Type Safety

• Full TypeScript implementation

• Zod schema validation

• Comprehensive interfaces

🐛 Troubleshooting

Authentication Errors

# Verify token is set
cat .env | grep MEDIUM_ACCESS_TOKEN

# Clear stored tokens
rm -f .medium-tokens.json

# Restart server
npm start

Build Errors

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

Rate Limiting

The client automatically handles rate limits. Check rate limit status:

const rateLimitInfo = client.getRateLimitInfo();
console.log(`Remaining: ${rateLimitInfo.remaining}`);

📊 What's New in v2.0.0

Added

• ✅ Real OAuth 2.0 authentication with token refresh

• ✅ Update article tool

• ✅ Delete article tool

• ✅ Get article details tool

• ✅ Get user profile tool

• ✅ Get drafts tool

• ✅ Exponential backoff retry logic

• ✅ Rate limit detection and handling

• ✅ Comprehensive test suite (Jest)

• ✅ Token persistence

Enhanced

• ✅ Publish article tool (added status & notify options)

• ✅ Better error messages

• ✅ Improved type safety

• ✅ Enhanced documentation

🚀 Roadmap

Phase 2 (Coming Soon)

• 📊 Analytics and article statistics

• 🖼️ Image upload support

• 🔍 Advanced search filters

• 🎯 SEO optimization tools

• 📝 Draft scheduling

Phase 3 (Future)

• 🤖 AI-powered content suggestions

• 📦 Bulk operations

• 🔄 Import/export functionality

• 👥 Collaboration features

• 🔔 Webhook support

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

• Medium API Docs: https://github.com/Medium/medium-api-docs

• MCP Protocol: https://github.com/modelcontextprotocol/sdk

• Issues: Create a GitHub issue for bugs or feature requests