mcp-server-medium 0.1.0__py3-none-any.whl

mcp_server_medium/__init__.py

@@ -0,0 +1,13 @@
+"""Medium MCP Server."""
+
+import asyncio
+
+from .server import main as _async_main
+
+
+def main() -> None:
+    """Synchronous entry point for the Medium MCP server."""
+    asyncio.run(_async_main())
+
+
+__all__ = ["main"]

mcp_server_medium/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running the server with `python -m mcp_server_medium`."""
+from . import main
+
+main()

mcp_server_medium/server.py

@@ -0,0 +1,554 @@
+"""
+Medium MCP Server
+
+An MCP server that provides tools to interact with the Medium API.
+Uses a self-issued access token (Integration Token) for authentication.
+
+Get your token at: https://medium.com/me/settings
+Set it as the MEDIUM_API_KEY environment variable.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+import feedparser
+import httpx
+import yaml
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+SERVER_NAME = "medium-mcp-server"
+MEDIUM_API_BASE = "https://api.medium.com/v1"
+
+server = Server(SERVER_NAME)
+
+
+def _get_api_key() -> str:
+    """Get the Medium API key.
+
+    Resolution order:
+    1. MEDIUM_API_KEY environment variable
+    2. ~/.medium/config.yaml (api_key field)
+    3. Fail fast with a clear error.
+    """
+    # 1. Environment variable
+    key = os.environ.get("MEDIUM_API_KEY")
+    if key:
+        return key
+
+    # 2. Config file
+    config_path = Path.home() / ".medium" / "config.yaml"
+    if config_path.is_file():
+        try:
+            with open(config_path) as f:
+                config = yaml.safe_load(f)
+            if isinstance(config, dict):
+                key = config.get("api_key") or config.get("API_KEY")
+                if key:
+                    return key
+        except Exception as exc:
+            raise RuntimeError(
+                f"Found {config_path} but failed to parse it: {exc}"
+            ) from exc
+
+    # 3. Fail fast
+    raise ValueError(
+        "No Medium API key found.\n\n"
+        "Set the MEDIUM_API_KEY environment variable, or create\n"
+        "  ~/.medium/config.yaml\n"
+        "with the following content:\n\n"
+        "  api_key: your_integration_token_here\n\n"
+        "Get your token at: https://medium.com/me/settings"
+    )
+
+
+async def _get_client() -> httpx.AsyncClient:
+    """Create an authenticated HTTPX client for the Medium API."""
+    api_key = _get_api_key()
+    return httpx.AsyncClient(
+        base_url=MEDIUM_API_BASE,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        },
+        timeout=30.0,
+    )
+
+
+# ──────────────────────────────────────────────
+# Tool definitions
+# ──────────────────────────────────────────────
+
+TOOLS = [
+    Tool(
+        name="get_profile",
+        description="Get the authenticated user's Medium profile (id, username, name, url, imageUrl)",
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    ),
+    Tool(
+        name="list_publications",
+        description="List all publications the authenticated user is related to (edits, writes, or follows)",
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    ),
+    Tool(
+        name="list_contributors",
+        description="List contributors for a given publication",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "publication_id": {
+                    "type": "string",
+                    "description": "The publication ID (from list_publications)",
+                }
+            },
+            "required": ["publication_id"],
+        },
+    ),
+    Tool(
+        name="create_post",
+        description="Create a post on the authenticated user's Medium profile",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "author_id": {
+                    "type": "string",
+                    "description": "The author's user ID (from get_profile)",
+                },
+                "title": {
+                    "type": "string",
+                    "description": "The title of the post (max 100 chars for SEO, must also be in content body)",
+                },
+                "content_format": {
+                    "type": "string",
+                    "description": "Format of the content: 'html' or 'markdown'",
+                    "enum": ["html", "markdown"],
+                },
+                "content": {
+                    "type": "string",
+                    "description": "The body of the post in HTML or Markdown format",
+                },
+                "tags": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Tags to classify the post (max 3, max 25 chars each)",
+                },
+                "publish_status": {
+                    "type": "string",
+                    "description": "Publish status: 'public', 'draft', or 'unlisted'",
+                    "enum": ["public", "draft", "unlisted"],
+                },
+                "canonical_url": {
+                    "type": "string",
+                    "description": "Original home of this content if published elsewhere",
+                },
+                "notify_followers": {
+                    "type": "boolean",
+                    "description": "Whether to notify followers of the publication",
+                },
+                "license": {
+                    "type": "string",
+                    "description": "License for the post",
+                    "enum": [
+                        "all-rights-reserved",
+                        "cc-40-by",
+                        "cc-40-by-sa",
+                        "cc-40-by-nd",
+                        "cc-40-by-nc",
+                        "cc-40-by-nc-nd",
+                        "cc-40-by-nc-sa",
+                        "cc-40-zero",
+                        "public-domain",
+                    ],
+                },
+            },
+            "required": ["author_id", "title", "content_format", "content"],
+        },
+    ),
+    Tool(
+        name="create_publication_post",
+        description="Create a post under a specific Medium publication",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "publication_id": {
+                    "type": "string",
+                    "description": "The publication ID to post under (from list_publications)",
+                },
+                "title": {
+                    "type": "string",
+                    "description": "The title of the post (max 100 chars for SEO)",
+                },
+                "content_format": {
+                    "type": "string",
+                    "description": "Format of the content: 'html' or 'markdown'",
+                    "enum": ["html", "markdown"],
+                },
+                "content": {
+                    "type": "string",
+                    "description": "The body of the post in HTML or Markdown format",
+                },
+                "tags": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Tags to classify the post (max 3, max 25 chars each)",
+                },
+                "publish_status": {
+                    "type": "string",
+                    "description": "Publish status. Writers can only use 'draft'. Editors can use 'public', 'draft', or 'unlisted'.",
+                    "enum": ["public", "draft", "unlisted"],
+                },
+                "canonical_url": {
+                    "type": "string",
+                    "description": "Original home of this content if published elsewhere",
+                },
+                "notify_followers": {
+                    "type": "boolean",
+                    "description": "Whether to notify followers of the publication",
+                },
+                "license": {
+                    "type": "string",
+                    "description": "License for the post",
+                    "enum": [
+                        "all-rights-reserved",
+                        "cc-40-by",
+                        "cc-40-by-sa",
+                        "cc-40-by-nd",
+                        "cc-40-by-nc",
+                        "cc-40-by-nc-nd",
+                        "cc-40-by-nc-sa",
+                        "cc-40-zero",
+                        "public-domain",
+                    ],
+                },
+            },
+            "required": ["publication_id", "title", "content_format", "content"],
+        },
+    ),
+    Tool(
+        name="upload_image",
+        description="Upload an image to Medium from a URL or file path",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "image_url": {
+                    "type": "string",
+                    "description": "Public URL of the image to upload. Medium will fetch and host it.",
+                }
+            },
+            "required": ["image_url"],
+        },
+    ),
+    Tool(
+        name="get_rss_feed",
+        description="Fetch and parse a Medium RSS feed into JSON. Supports profile (@username), publication (publication-name), topic feeds (tag/tag-name), or any full feed URL",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "feed_url": {
+                    "type": "string",
+                    "description": "RSS feed URL or shorthand. Examples: '@username', 'publication-name', 'tag/software-engineering', or full URL like 'https://medium.com/feed/@username'",
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Max number of entries to return (default: all)",
+                },
+            },
+            "required": ["feed_url"],
+        },
+    ),
+]
+
+
+# ──────────────────────────────────────────────
+# Tool handlers
+# ──────────────────────────────────────────────
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return TOOLS
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+    if name == "get_rss_feed":
+        return await _handle_get_rss_feed(arguments)
+
+    async with await _get_client() as client:
+        if name == "get_profile":
+            return await _handle_get_profile(client, arguments)
+        elif name == "list_publications":
+            return await _handle_list_publications(client, arguments)
+        elif name == "list_contributors":
+            return await _handle_list_contributors(client, arguments)
+        elif name == "create_post":
+            return await _handle_create_post(client, arguments)
+        elif name == "create_publication_post":
+            return await _handle_create_publication_post(client, arguments)
+        elif name == "upload_image":
+            return await _handle_upload_image(client, arguments)
+        else:
+            raise ValueError(f"Unknown tool: {name}")
+
+
+async def _handle_get_profile(
+    client: httpx.AsyncClient, arguments: dict[str, Any]
+) -> list[TextContent]:
+    """GET /v1/me"""
+    resp = await client.get("/me")
+    resp.raise_for_status()
+    data = resp.json()
+    return [TextContent(type="text", text=_format_json(data))]
+
+
+async def _handle_list_publications(
+    client: httpx.AsyncClient, arguments: dict[str, Any]
+) -> list[TextContent]:
+    """First get the user id, then GET /v1/users/{userId}/publications"""
+    me_resp = await client.get("/me")
+    me_resp.raise_for_status()
+    user_id = me_resp.json()["data"]["id"]
+
+    resp = await client.get(f"/users/{user_id}/publications")
+    resp.raise_for_status()
+    data = resp.json()
+    return [TextContent(type="text", text=_format_json(data))]
+
+
+async def _handle_list_contributors(
+    client: httpx.AsyncClient, arguments: dict[str, Any]
+) -> list[TextContent]:
+    """GET /v1/publications/{publicationId}/contributors"""
+    publication_id = arguments["publication_id"]
+    resp = await client.get(f"/publications/{publication_id}/contributors")
+    resp.raise_for_status()
+    data = resp.json()
+    return [TextContent(type="text", text=_format_json(data))]
+
+
+async def _handle_create_post(
+    client: httpx.AsyncClient, arguments: dict[str, Any]
+) -> list[TextContent]:
+    """POST /v1/users/{authorId}/posts"""
+    author_id = arguments.pop("author_id")
+
+    body: dict[str, Any] = {
+        "title": arguments.pop("title"),
+        "contentFormat": arguments.pop("content_format"),
+        "content": arguments.pop("content"),
+    }
+
+    if "tags" in arguments and arguments["tags"]:
+        body["tags"] = arguments.pop("tags")
+    if "publish_status" in arguments and arguments["publish_status"]:
+        body["publishStatus"] = arguments.pop("publish_status")
+    if "canonical_url" in arguments and arguments["canonical_url"]:
+        body["canonicalUrl"] = arguments.pop("canonical_url")
+    if "notify_followers" in arguments and arguments["notify_followers"] is not None:
+        body["notifyFollowers"] = arguments.pop("notify_followers")
+    if "license" in arguments and arguments["license"]:
+        body["license"] = arguments.pop("license")
+
+    resp = await client.post(f"/users/{author_id}/posts", json=body)
+    resp.raise_for_status()
+    data = resp.json()
+    return [TextContent(type="text", text=_format_json(data))]
+
+
+async def _handle_create_publication_post(
+    client: httpx.AsyncClient, arguments: dict[str, Any]
+) -> list[TextContent]:
+    """POST /v1/publications/{publicationId}/posts"""
+    publication_id = arguments.pop("publication_id")
+
+    body: dict[str, Any] = {
+        "title": arguments.pop("title"),
+        "contentFormat": arguments.pop("content_format"),
+        "content": arguments.pop("content"),
+    }
+
+    if "tags" in arguments and arguments["tags"]:
+        body["tags"] = arguments.pop("tags")
+    if "publish_status" in arguments and arguments["publish_status"]:
+        body["publishStatus"] = arguments.pop("publish_status")
+    if "canonical_url" in arguments and arguments["canonical_url"]:
+        body["canonicalUrl"] = arguments.pop("canonical_url")
+    if "notify_followers" in arguments and arguments["notify_followers"] is not None:
+        body["notifyFollowers"] = arguments.pop("notify_followers")
+    if "license" in arguments and arguments["license"]:
+        body["license"] = arguments.pop("license")
+
+    resp = await client.post(f"/publications/{publication_id}/posts", json=body)
+    resp.raise_for_status()
+    data = resp.json()
+    return [TextContent(type="text", text=_format_json(data))]
+
+
+async def _handle_upload_image(
+    client: httpx.AsyncClient, arguments: dict[str, Any]
+) -> list[TextContent]:
+    """
+    POST /v1/images
+
+    Medium auto-sideloads images in post content, but this endpoint
+    is available for uploading images independently.
+    """
+    image_url = arguments["image_url"]
+
+    # Download the image first, then upload to Medium
+    async with httpx.AsyncClient(timeout=30.0) as dl_client:
+        img_resp = await dl_client.get(image_url)
+        img_resp.raise_for_status()
+
+    content_type = img_resp.headers.get("content-type", "image/png")
+    image_data = img_resp.content
+
+    # Upload to Medium via multipart form
+    files = {
+        "image": ("image", image_data, content_type),
+    }
+    upload_resp = await client.post("/images", files=files)
+    upload_resp.raise_for_status()
+    data = upload_resp.json()
+    return [TextContent(type="text", text=_format_json(data))]
+
+
+# ──────────────────────────────────────────────
+# RSS feed handler
+# ──────────────────────────────────────────────
+
+
+def _resolve_feed_url(feed_url: str) -> str:
+    """Resolve shorthand URLs to full Medium RSS feed URLs."""
+    url = feed_url.strip()
+
+    # Already a full URL
+    if url.startswith("http://") or url.startswith("https://"):
+        return url
+
+    # Ensure we start from medium.com
+    base = "https://medium.com/feed"
+
+    # @username → medium.com/feed/@username
+    if url.startswith("@"):
+        return f"{base}/{url}"
+
+    # tag/tag-name → medium.com/feed/tag/tag-name
+    if url.startswith("tag/"):
+        return f"{base}/{url}"
+
+    # publication-name/tagged/tag-name → medium.com/feed/publication-name/tagged/tag-name
+    if "/tagged/" in url:
+        return f"{base}/{url}"
+
+    # Plain name → medium.com/feed/publication-name
+    return f"{base}/{url}"
+
+
+async def _handle_get_rss_feed(arguments: dict[str, Any]) -> list[TextContent]:
+    """Fetch and parse a Medium RSS feed."""
+    feed_url = _resolve_feed_url(arguments["feed_url"])
+    limit = arguments.get("limit")
+
+    # Use feedparser to parse the RSS XML
+    loop = asyncio.get_running_loop()
+
+    def _parse() -> dict:
+        # feedparser.parse() handles HTTP fetching internally
+        feed = feedparser.parse(feed_url)
+
+        if feed.bozo and not feed.entries:
+            # Parse error — feed.bozo_exception has details
+            raise RuntimeError(
+                f"Failed to parse RSS feed: {feed.bozo_exception}"
+            )
+
+        result: dict[str, Any] = {
+            "feed": {
+                "title": feed.feed.get("title", ""),
+                "link": feed.feed.get("link", ""),
+                "description": feed.feed.get("subtitle", ""),
+            },
+            "entries": [],
+        }
+
+        entries = feed.entries
+        if limit:
+            entries = entries[:limit]
+
+        for entry in entries:
+            result["entries"].append({
+                "id": entry.get("id", ""),
+                "title": entry.get("title", ""),
+                "link": entry.get("link", ""),
+                "published": entry.get("published", ""),
+                "published_parsed": (
+                    time.strftime("%Y-%m-%dT%H:%M:%SZ", entry["published_parsed"])
+                    if entry.get("published_parsed")
+                    else None
+                ),
+                "author": entry.get("author", ""),
+                "author_link": (
+                    entry.get("author_detail", {}).get("href", "")
+                    if entry.get("author_detail")
+                    else ""
+                ),
+                "tags": [
+                    tag.get("term", "")
+                    for tag in entry.get("tags", [])
+                ],
+                "summary": entry.get("summary", ""),
+                "content_html": (
+                    entry.get("content", [{}])[0].get("value", "")
+                    if entry.get("content")
+                    else ""
+                ),
+                "thumbnail": (
+                    entry.get("media_thumbnail", [{}])[0].get("url", "")
+                    if entry.get("media_thumbnail")
+                    else ""
+                ),
+            })
+
+        return result
+
+    data = await loop.run_in_executor(None, _parse)
+    return [TextContent(type="text", text=_format_json(data))]
+
+
+# ──────────────────────────────────────────────
+# Helpers
+# ──────────────────────────────────────────────
+
+
+def _format_json(data: dict[str, Any]) -> str:
+    """Pretty-print JSON response."""
+    import json
+
+    return json.dumps(data, indent=2, ensure_ascii=False)
+
+
+# ──────────────────────────────────────────────
+# Main entry
+# ──────────────────────────────────────────────
+
+
+async def main() -> None:
+    """Run the MCP server over stdio."""
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())

mcp_server_medium-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.3
+Name: mcp-server-medium
+Version: 0.1.0
+Summary: MCP server for Medium API — publish posts, manage publications, RSS feeds, upload images
+Author: afikrim
+Author-email: afikrim <afikrim10@gmail.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=1.28.1
+Requires-Dist: feedparser>=6.0.12
+Requires-Dist: pyyaml>=5.4
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/afikrim/medium-mcp-server
+Project-URL: Repository, https://github.com/afikrim/medium-mcp-server
+Description-Content-Type: text/markdown
+
+# MCP Server Medium
+
+MCP (Model Context Protocol) server for interacting with the Medium API. Allows AI agents to publish posts, manage publications, upload images, and parse RSS feeds to JSON.
+
+## Quick Start
+
+```bash
+# Run with uvx (no install needed) — uses MEDIUM_API_KEY env var
+MEDIUM_API_KEY=your_token_here uvx mcp-server-medium
+
+# Or use a config file instead
+mkdir -p ~/.medium
+echo 'api_key: your_token_here' > ~/.medium/config.yaml
+uvx mcp-server-medium
+
+# Or install and run
+uv tool install mcp-server-medium
+mcp-server-medium
+```
+
+## Authentication
+
+The server resolves your API key in this order:
+
+1. **`MEDIUM_API_KEY` environment variable** — best for MCP clients
+2. **`~/.medium/config.yaml`** — persistent local config
+
+Create `~/.medium/config.yaml`:
+```yaml
+api_key: your_integration_token_here
+```
+
+Get your token at [medium.com/me/settings](https://medium.com/me/settings) (look for "Integration Tokens").
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_profile` | Get the authenticated user's Medium profile |
+| `list_publications` | List all publications the user is related to |
+| `list_contributors` | List contributors for a publication |
+| `create_post` | Create a post on the user's Medium profile |
+| `create_publication_post` | Create a post under a specific publication |
+| `upload_image` | Upload an image to Medium from a URL |
+| `get_rss_feed` | Fetch and parse Medium RSS feeds into JSON |
+
+### RSS Feed Shorthands
+
+The `get_rss_feed` tool accepts flexible input:
+
+| Shorthand | Resolves to |
+|-----------|------------|
+| `@username` | `https://medium.com/feed/@username` |
+| `publication-name` | `https://medium.com/feed/publication-name` |
+| `tag/tag-name` | `https://medium.com/feed/tag/tag-name` |
+| `pub-name/tagged/tag` | `https://medium.com/feed/pub-name/tagged/tag` |
+| Full URL | Used as-is |
+
+## Development
+
+```bash
+# Clone and setup
+git clone https://github.com/afikrim/medium-mcp-server
+cd medium-mcp-server
+uv sync
+
+# Run locally
+MEDIUM_API_KEY=your_key uv run medium-mcp-server
+
+# Use with MCP inspector
+MEDIUM_API_KEY=your_key npx @modelcontextprotocol/inspector uv run medium-mcp-server
+```
+
+## Configuration
+
+Configure in your MCP client (e.g., Claude Desktop, Cursor):
+
+```json
+{
+  "mcpServers": {
+    "medium": {
+      "command": "uvx",
+      "args": ["mcp-server-medium"],
+      "env": {
+        "MEDIUM_API_KEY": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+Or using the config file (no env needed):
+
+```json
+{
+  "mcpServers": {
+    "medium": {
+      "command": "uvx",
+      "args": ["mcp-server-medium"]
+    }
+  }
+}
+```
+
+With `~/.medium/config.yaml`:
+```yaml
+api_key: your_token_here
+```
+
+## License
+
+MIT

mcp_server_medium-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mcp_server_medium/__init__.py,sha256=t_eVNrCRWwvSIFvPvlWPuBMGyCF5hUR7dkSMTcpkuBY,217
+mcp_server_medium/__main__.py,sha256=WAS0NBPSKx5pEwTcGhUN9IKRPKknMg70ArYh7zCLoZw,94
+mcp_server_medium/server.py,sha256=_EbFHWe809Aql55MaAnCyHnCf2y0WbW3y7YSUQLVJ8E,20191
+mcp_server_medium-0.1.0.dist-info/WHEEL,sha256=wXwAVsgVaOZ_pwDFqQm5Rd6PID-Fc74nkLc8X8gHiDo,81
+mcp_server_medium-0.1.0.dist-info/entry_points.txt,sha256=aO30DN3bfydOGE5se36vaAnttqCVvpb8CW70YAFVF5Q,62
+mcp_server_medium-0.1.0.dist-info/METADATA,sha256=0tpeh0v2tBA9hjB-ivf5rEosAZ_Oa9s2OkRBbUYpK2Y,3231
+mcp_server_medium-0.1.0.dist-info/RECORD,,

mcp_server_medium-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.19
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_server_medium-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mcp-server-medium = mcp_server_medium:main
+