docs/API.md

Medium-MCP API Reference

Overview

Medium-MCP provides a Model Context Protocol (MCP) server for scraping Medium articles.

---

MCP Tools

medium_scrape

Scrape a single Medium article.

Parameters:

Name	Type	Required	Description
url	string	✅	Medium article URL
force_refresh	boolean	❌	Bypass cache (default: false)
output_format	string	❌	"markdown", "html", or "both"

Response:

{
  "url": "https://medium.com/...",
  "title": "Article Title",
  "author": {"name": "...", "username": "..."},
  "markdown_content": "...",
  "html_content": "...",
  "reading_time": 5,
  "is_paywalled": false
}

---

medium_batch

Scrape multiple articles in parallel.

Parameters:

Name	Type	Required	Description
urls	string[]	✅	List of URLs (max 20)

Response:

{
  "success": [...],
  "failed": [{"url": "...", "error": "..."}],
  "total": 5,
  "success_count": 4,
  "fail_count": 1
}

---

medium_search

Search for articles.

Parameters:

Name	Type	Required	Description
query	string	✅	Search query
max_results	number	❌	Max results (1-20)

Response:

[
  {"title": "...", "url": "...", "author": "..."}
]

---

medium_fresh

Browse trending articles by tag.

Parameters:

Name	Type	Required	Description
tag	string	✅	Tag name (e.g., "python")
max_articles	number	❌	Max articles (1-20)

---

medium_export

Export article to file.

Parameters:

Name	Type	Required	Description
url	string	✅	Article URL
format	string	❌	"pdf", "html", "json", "md"

---

medium_tts

Convert article to audio.

Parameters:

Name	Type	Required	Description
url	string	✅	Article URL
voice	string	❌	Voice name (default: "george")

---

Error Codes

Code	HTTP	Description
INVALID_URL	400	Invalid URL format
ARTICLE_NOT_FOUND	404	Article not found
RATE_LIMITED	429	Rate limit exceeded
SCRAPE_FAILED	502	Scraping failed
TIMEOUT	504	Request timeout

---

Rate Limits

• 60 requests/minute per client
• 1000 requests/hour daily limit
• Burst limit: 10 requests

---

Environment Variables

Variable	Required	Description
GROQ_API_KEY	✅	Groq API for LLM
ELEVENLABS_API_KEY	❌	ElevenLabs TTS
GEMINI_API_KEY	❌	Gemini fallback