BlogCast MCP

One post. Every platform. Powered by Notion + Claude.

BlogCast MCP is an open-source Model Context Protocol server that turns Notion into a headless CMS and publishing hub. Write once in the dashboard or in Notion, then use Claude (or the dashboard) to publish simultaneously to Dev.to, Hashnode, Medium, and more.

What's Inside

Quickstart

Prerequisites

• Node.js 20+, npm 10+
• A Notion account with API access
• Claude Desktop (for MCP tools) — optional if you only use the dashboard

1. Clone & install

git clone https://github.com/thecodedaniel/blogcast-mcp.git
cd blogcast
npm install

2. Run everything

npm run dev          # starts server (3001) + client (5173)

Or run individually:

npm run dev:server   # Express backend only
npm run dev:client   # React dashboard only
npm run dev:mcp      # MCP server only (for testing)

3. Open the dashboard

Navigate to http://localhost:5173 — the Settings page will guide you through:

1. Notion integration — API key + database IDs
2. Platform credentials — Dev.to, Hashnode, Medium API keys
3. AI features — Anthropic API key (optional, unlocks smart pre-publish checks)
4. Claude Desktop — one-click auto-configure (no manual JSON editing)

First run: Once you add your Notion credentials, BlogCast automatically sets up all required database columns (idempotent — safe to re-run at any time).

4. Set up Notion

1. Go to notion.so/my-integrations and create a new integration
2. Create two databases in Notion: BlogCast Posts and BlogCast Analytics
3. Share both databases with your integration (open each DB → ⋯ → Connections → add your integration)
4. Copy the database IDs from the page URLs (the 32-char string after the last /)
5. Add both IDs in localhost:5173/settings

BlogCast will automatically add all required columns to both databases on first run.

5. Build the MCP server (for Claude Desktop)

npm run build:mcp

Then in Settings, click "Connect Claude Desktop" — BlogCast will auto-configure claude_desktop_config.json for you.

Or add manually to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "blogcast": {
      "command": "node",
      "args": ["/absolute/path/to/blogcast/mcp/dist/index.js"],
      "env": {
        "BACKEND_URL": "http://localhost:3001"
      }
    }
  }
}

Writing Posts

Option A — In the Dashboard (recommended)

1. Click Write in the sidebar
2. Type your title and write your post using the rich text editor
   • Full toolbar: bold, italic, headings, inline code, code blocks with syntax highlighting (TypeScript, Python, Dart, Go, Rust, and 20+ more languages)
   • Live Preview mode toggle
3. Add tags, excerpt, and choose target platforms in the right sidebar
4. Click Save Draft (saves to Notion) or Save & Publish (saves + publishes immediately)

Option B — In Notion directly

1. Open your BlogCast Posts database in Notion
2. Click + New and write your post content inside the page
3. Fill in the properties: Title, Tags, Publish To, Excerpt
4. Set Status to Draft — it appears in the dashboard automatically

Publishing

Via the Dashboard

1. Write → Save & Publish — write and publish in one step
2. Posts → click any post → redirects to Publish page → choose platforms → click Publish

Via Claude (MCP)

"Show me my draft posts"
"Preview my latest Notion draft"
"Publish my post about TypeScript to Dev.to and Hashnode"
"What's the status of my last post?"
"Schedule my React post for tomorrow at 9am UTC on all platforms"
"Add my Hashnode API key"
"Sync analytics for my last 5 posts"

MCP Tools

AI Features

When an Anthropic API key is configured (Settings → AI Features):

AI features are fully optional and degrade gracefully — publishing works normally without an Anthropic key.

Architecture

Notion Workspace (CMS + Analytics DB)
        │ Notion API
        ▼
BlogCast MCP Server (stdio, Claude integration)
        │ HTTP
        ▼
Express Backend (localhost:3001)
  ├── Publishers: Dev.to, Hashnode, Medium (draft)
  ├── AI service (Anthropic SDK — pre-publish checks, content adaptation)
  ├── Image service (download → cache → re-upload)
  ├── Format service (Markdown ↔ HTML)
  ├── Auth vault (encrypted local credentials)
  ├── Setup service (Notion DB auto-migration on startup)
  └── Scheduler (auto-publish at scheduled time)
        │
        ▼
Local Storage (./storage/)
  ├── images/   — cached images with deduplication
  ├── queue/    — pending publish jobs
  └── logs/     — winston logs

React Dashboard (localhost:5173)
  ├── Write     — TipTap rich text editor with syntax-highlighted code blocks
  ├── Posts     — list, search, filter all posts from Notion
  ├── Publish   — select post + platforms + AI pre-publish check
  ├── Platforms — add/remove/test API keys
  └── Settings  — Notion config, AI config, Claude Desktop auto-connect

Image Handling

Notion CDN URLs expire after ~1 hour. BlogCast handles this transparently:

1. Images are downloaded from Notion and cached locally in storage/images/
2. Each image is hashed by URL (SHA-256) for deduplication
3. On publish, images are uploaded to each platform's CDN
4. Platform CDN URLs are cached so re-publishing doesn't re-upload

Notion Database Schema

Posts DB (BlogCast Posts)

Analytics DB (BlogCast Analytics)

All columns are auto-created when you first configure Notion credentials. No manual database setup required.

Environment Variables

Almost nothing needs to go in .env. All credentials and settings are configured through the Settings page (localhost:5173/settings) and stored encrypted on your local machine.

The only optional env vars are:

See .env.example for the template.

Supported Platforms

License

MIT — built with ❤️ by THECODEDANIEL LIMITED