ghost-writer-mcp 0.2.0

MCP server that turns GitHub activity into LinkedIn thought leadership

Ghost Writer MCP

An MCP server that scans your Git repositories, identifies interesting engineering work, and generates LinkedIn post drafts — with built-in confidentiality sanitisation.

What it does

Your repos → scan activity → classify by content potential → generate draft → sanitise → review

1. Scan — reads git log from local repo clones (zero API calls, instant)
2. Aggregate — groups commits by conventional-commit prefix and clusters related work
3. Classify — LLM ranks groups by content potential, assigns pillars and angles
4. Generate — LLM writes a LinkedIn draft in your chosen format (war story, hot take, tactical howto, TIL, deep dive)
5. Sanitise — three-gate safety: regex blocklist → LLM review → human review

Quick start

Prerequisites

• Python 3.12+
• uv (recommended) or pip
• An LLM provider: Ollama (free, local) or an Anthropic API key
• Local clones of the repos you want to scan

Install

Option A — clone and run (recommended for customisation):

git clone https://github.com/fabdendev/ghost-writer-mcp.git
cd ghost-writer-mcp
uv sync

Option B — run directly with uvx (no clone needed):

uvx ghost-writer-mcp

Configure

cp config.example.yaml config.yaml

Edit config.yaml with your repos, blocklist, and LLM settings. See config.example.yaml for a fully documented template.

For Ollama (free, local):

llm:
  provider: ollama
  base_url: "http://localhost:11434/v1"
  classifier_model: qwen3:8b
  generator_model: qwen3:8b
  api_key: "ollama"

ollama pull qwen3:8b
ollama serve

For Anthropic (cloud):

llm:
  provider: anthropic
  classifier_model: claude-haiku-4-5-20251001
  generator_model: claude-haiku-4-5-20251001
  api_key: "${ANTHROPIC_API_KEY}"

echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

Add to Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json):

If installed from clone:

{
  "mcpServers": {
    "ghost-writer": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ghost-writer-mcp", "fastmcp", "run", "src/server.py"]
    }
  }
}

If using uvx:

{
  "mcpServers": {
    "ghost-writer": {
      "command": "uvx",
      "args": ["ghost-writer-mcp"]
    }
  }
}

Use via MCP

From Claude Code (or any MCP client):

scan_activity                          # scan all configured repos (last 7 days)
scan_activity(repo="my-project")       # scan a single repo
scan_activity(days=30)                 # look back 30 days
generate_draft(activity_index=1)       # generate from top candidate
generate_draft(3, format="hot_take")   # override format
edit_draft(1, "make it shorter")       # refine with natural language
list_drafts(status="pending")          # see saved drafts

Use via CLI

You can also test without an MCP client:

uv run python -m src scan --days 14                    # scan all repos
uv run python -m src scan --repo my-project            # scan one repo
uv run python -m src generate 1                        # draft from top result
uv run python -m src generate 3 --format hot_take      # override format
uv run python -m src list                              # list saved drafts

Tools

Tool	Description
scan_activity	Scan repos, aggregate commits, classify and rank by content potential
generate_draft	Generate a LinkedIn draft from a classified activity
edit_draft	Refine a draft with natural language instructions
list_drafts	List saved drafts, optionally filtered by status

Scanning modes

Ghost Writer supports two scanning backends:

• Local git (default) — reads git log from local clones. Zero API calls, instant results. Set local_path on each repo in your config.
• GitHub API (fallback) — used automatically for repos without local_path. Requires a GitHub token (github.token in config). Fetches up to 30 commits and 20 merged PRs per repo.

You can mix both: some repos with local clones, others via API.

Confidentiality

Ghost Writer uses three safety gates to prevent leaking sensitive information:

• Gate 1 — Blocklist: regex-based detection and replacement of company names, client names, product names, infrastructure details, and people names
• Gate 2 — LLM Review: the LLM scans generated text for anything that looks confidential and flags it
• Gate 3 — Human Review: drafts are saved as pending — you always get the final say

Configure your blocklist and abstractions in config.yaml:

sanitisation:
  blocklist:
    company_names: ["Acme Corp"]
    client_names: ["Big Client"]
    product_names: ["internal-tool"]
    infrastructure: ["prod-db-01.internal"]
    people: ["John Doe"]
  abstractions:
    "Acme Corp": "a mid-size tech company"
    "internal-tool": "an internal platform"

Content pillars

Define what topics you want to post about. The classifier maps activities to pillars:

content:
  pillars:
    - name: ai_engineering
      description: "Building AI agents, LLM integration, prompt engineering"
      repo_signals: ["agent", "llm", "prompt"]
      weight: 1.0
    - name: data_architecture
      description: "Data pipelines, ETL, event-driven systems"
      repo_signals: ["pipeline", "etl", "kafka"]
      weight: 0.8

Post formats

Format	Description
tactical_howto	Problem → 3-5 concrete steps → takeaway
hot_take	Contrarian claim backed by one specific thing you built
war_story	What broke, what you tried, what worked, the lesson
til	One surprising thing you learned, under 500 chars
deep_dive	3-4 sections with trade-offs and alternatives

Architecture

src/
├── server.py              # FastMCP server (4 tools)
├── cli.py                 # Standalone CLI for testing without MCP
├── config.py              # Pydantic config with env/shell resolution
├── llm_client.py          # Unified Anthropic + OpenAI-compatible client
├── scanner/
│   ├── local_git.py       # Git CLI scanner (primary)
│   ├── github_client.py   # GitHub API scanner (alternative)
│   ├── aggregator.py      # Commit grouping and clustering
│   └── activity.py        # ActivityItem dataclass
├── content/
│   ├── classifier.py      # LLM-based content scoring
│   ├── generator.py       # Draft generation with sanitisation
│   ├── abstractor.py      # Two-gate confidentiality layer
│   └── prompts/           # System prompts (classifier, generator, reviewer)
└── store/
    ├── database.py         # SQLite persistence
    └── blocklist.py        # Regex-based blocklist

Development

uv sync --extra dev
uv run pytest                 # run tests
uv run ruff check src/ tests/ # lint

License

MIT