# @houtini/contentmarketingideas

[![npm version](https://img.shields.io/npm/v/@houtini/contentmarketingideas.svg?style=flat-square)](https://www.npmjs.com/package/@houtini/contentmarketingideas)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)

The MCP server for [Content Marketing Ideas](https://contentmarketingideas.co) — the editorial copilot I built because I was tired of the same content research loop. You read a lot, you notice patterns, you get ideas, you write. The reading and pattern-spotting is the slow part, and most of it is mechanical.

This server pulls all of it into Claude Desktop, Claude Code, Cursor, or any MCP client: source monitoring, editorial briefs, voice-matched article drafts, RAG corpus search, Google Search Console data, and WordPress publishing. Around 70 tools, one `npx` command.

I wrote a long post about why the product exists and how I use it every day: [Content Marketing Ideas — what it is, how I built it, and why I use it](https://houtini.com/content-marketing-ideas-what-it-is-how-i-built-it-and-why-i-use-it-every-day/).

---

> **Quick Navigation**
>
> [Get started](#get-started-in-two-minutes) | [What it does](#what-it-does) | [Tools reference](#tools-reference) | [Configuration](#configuration-reference) | [Requirements](#requirements)

---

## Get started in two minutes

**Step 1: Get an account and an API key**

Sign up at [contentmarketingideas.co](https://contentmarketingideas.co). Free tier covers five sources and weekly delivery, which is enough to wire the MCP up and try every tool. Once you're in, go to **Dashboard → Account → API & MCP Server** and click **Generate API Key**. The full key is shown once — copy it now. Keys are prefixed `cr_`.

**Step 2: Add to your Claude Desktop config**

Config file locations:
- Windows: `C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "contentmarketingideas": {
      "command": "npx",
      "args": ["-y", "@houtini/contentmarketingideas"],
      "env": {
        "CMI_API_KEY": "cr_your_api_key_here"
      }
    }
  }
}
```

**Step 3: Restart Claude Desktop**

Tools show up automatically. `npx` pulls the package on first run — no separate install needed.

### Claude Code (CLI)

Claude Code uses `claude mcp add` rather than the desktop config file:

```bash
claude mcp add -e CMI_API_KEY=cr_your_api_key_here -s user contentmarketingideas -- npx -y @houtini/contentmarketingideas
```

Verify with `claude mcp get contentmarketingideas` — you should see `Status: Connected`.

### Cursor / Windsurf / VS Code

Same shape, different config file. Add this block:

```json
{
  "contentmarketingideas": {
    "command": "npx",
    "args": ["-y", "@houtini/contentmarketingideas"],
    "env": {
      "CMI_API_KEY": "cr_your_api_key_here"
    }
  }
}
```

### Local build instead

For development, or if you'd rather not rely on npx:

```bash
git clone https://github.com/houtini-ai/contentmarketingideas-mcp
cd contentmarketingideas-mcp
npm install
npm run build
```

Then point your config at the local build:

```json
{
  "mcpServers": {
    "contentmarketingideas": {
      "command": "node",
      "args": ["C:/path/to/contentmarketingideas-mcp/dist/index.js"],
      "env": {
        "CMI_API_KEY": "cr_your_api_key_here"
      }
    }
  }
}
```

---

## What it does

Content Marketing Ideas isn't a "here's what's trending" feed. It's an editorial copilot — every brief is framed as *"here's what you should write and why"* rather than a data dump. The MCP exposes the same engine to Claude.

### Editorial briefs from your sources

```
Use contentmarketingideas:list_briefs to show me this week's briefs for site-ae01a256
```

The product watches RSS feeds, YouTube channels, subreddits, podcasts, and news keywords for you. When something relevant lands, four signal generators (trending, decay, untapped, gap) write briefs containing a thesis, editorial play, gap analysis, suggested format, what to cover, internal link suggestions, and two alternative angles (obvious / bold / contrarian). Each brief is enriched with keyword volume, difficulty, monthly trend, People Also Ask questions, competitive landscape, entity relationships from Wikidata, and an originality score versus existing coverage.

`get_brief` returns the full payload — synthesis, signal sources, enrichment, momentum sparkline, the lot. `brief_feedback` lets you train the system from inside Claude (`thumbs_up` / `thumbs_down` / `made_this` / `already_covered`). Thumbs-down auto-archives briefs you don't want to see again.

### Voice-matched article generation

```
Use contentmarketingideas:create_article with source_type="brief" and source_id="<brief_id>"
```

The web app analyses your published content with sixteen statistical analysers and produces a deterministic ~17KB writing-style guide. Article generation feeds that guide into Claude Sonnet so the output reads like you wrote it — not like an LLM. 1,300–1,800 words, full markdown, with Schema.org provenance and entity-tagged facts traceable back to the source.

`generate_article` queues an article for the production pipeline, `regenerate_article` re-runs failed jobs, `get_article_provenance` returns the source chain and Schema.org JSON-LD, and `publish_article` pushes the finished post straight to WordPress over the REST API (credentials encrypted at rest).

### Topic Explorer — coverage as a map, not a list

```
Use contentmarketingideas:get_coverage_explore for site-ae01a256
```

Topics are the unit of value. The Topic Explorer assembles every entity from your last 100 briefs plus your site's core topics, then enriches each with corpus matches, GSC traffic and 28-day sparklines, search volume, competitive landscape, parent/sibling topics from Wikidata, and a lifecycle state: **covered**, **trending**, **gap**, **declining**, or **emerging**. `get_coverage_explore` returns the full clustered dataset so you can ask Claude things like *"which trending topics do I have zero coverage on?"* or *"cluster my declining pages by parent topic and suggest refreshes."*

### Search Console integration

```
Use contentmarketingideas:gsc_growing_queries with site_id="..." and limit=20
```

GSC OAuth is per-site. Once connected, daily data feeds into brief generation and is queryable through the MCP: `gsc_summary`, `gsc_queries`, `gsc_opportunities` (high-impression, low-position), `gsc_growing_queries`, `gsc_declining_queries`, `gsc_growing_pages`, `gsc_declining_pages`, `gsc_daily_summary` for sparklines.

### RAG corpus — your own knowledge base inside Claude

```
Use contentmarketingideas:search_rag with q="long-tail audience research methods" and limit=10
```

The corpus is human-curated by design — your own published content, the sources you follow, and URLs you add manually. No auto-crawling junk. Documents are indexed into Cloudflare Vectorize (bge-m3, 1024d) and a D1 FTS5 index for hybrid semantic + keyword search. Long structured documents get section-aware embeddings with parent_id linkage, and queries dedupe sections back to their parent doc with a small breadth bonus.

`populate_corpus` indexes a list of URLs, `populate_site` walks a sitemap, `populate_youtube` pulls full transcripts from a YouTube channel. `list_corpus_documents`, `delete_corpus_document`, `rag_stats`, and `search_rag` round it out. Site-scoped — sources for site A don't pollinate site B's briefs.

### Source management

```
Use contentmarketingideas:detect_source with url="https://example.com/feed"
```

`detect_source` auto-identifies feed type (RSS, YouTube, Reddit, podcast, news) and resolves the canonical feed URL. `add_source`, `update_source`, `delete_source`, `list_sources`, `get_source` cover the rest. Sources are site-scoped, so a multi-site account never cross-contaminates briefs.

### Pipeline triggers

```
Use contentmarketingideas:trigger_synthesis to generate briefs now
```

Don't want to wait for the cron run? `trigger_ingestion` runs all your sources, `trigger_synthesis` generates briefs from current content, `trigger_profile` re-runs site profile analysis (voice guide, topics, audience, content gaps). Useful for testing and for end-of-day "what came in today" runs.

### Account, sites, deliveries, WordPress

Multi-site accounts are first-class. `list_sites` / `create_site` / `update_site` / `delete_site` / `update_site_schedule` for site management; `list_account_emails` / `add_account_email` / `delete_account_email` for multi-recipient delivery (Business+); `get_wordpress_status` / `save_wordpress_credentials` / `delete_wordpress_credentials` for publishing; `list_deliveries` for the email delivery audit trail.

---

## Tools reference

Around 70 tools across seven groups.

### Briefs

| Tool | Description |
|------|-------------|
| `list_briefs` | List editorial briefs with filters (site, status, signal type, search) |
| `get_brief` | Full brief detail: synthesis, enrichment, keywords, signals, momentum |
| `brief_feedback` | Submit feedback (`thumbs_up`, `thumbs_down`, `made_this`, `already_covered`) |
| `delete_brief` | Delete a brief |
| `generate_draft` | Generate a voice-matched draft from a brief |
| `get_draft` | Get the generated draft text |

### Sources

| Tool | Description |
|------|-------------|
| `list_sources` | List content sources, optionally filtered by site |
| `get_source` | Source details and item count |
| `add_source` | Add RSS, YouTube, Reddit, podcast, or news source |
| `update_source` | Rename or set keyword filters / tags |
| `delete_source` | Remove a source |
| `detect_source` | Auto-detect source type from URL |

### Articles

| Tool | Description |
|------|-------------|
| `list_articles` | List articles for a site |
| `get_article` | Full article with markdown, outline, research |
| `create_article` | Create from a brief, growth item, or custom prompt |
| `update_article` | Edit title, markdown, keywords, notes |
| `delete_article` | Delete an article |
| `generate_article` | Queue an article for AI generation |
| `regenerate_article` | Re-run a failed or completed article |
| `publish_article` | Publish to WordPress |
| `get_publish_status` | Check WordPress publish status |
| `get_article_provenance` | Source attribution + Schema.org JSON-LD |

### RAG corpus

| Tool | Description |
|------|-------------|
| `list_corpus_documents` | List indexed documents |
| `delete_corpus_document` | Remove a document |
| `search_rag` | Hybrid semantic + keyword search |
| `rag_stats` | Corpus statistics |
| `populate_corpus` | Index URLs into the corpus |
| `populate_site` | Index a site via sitemap |
| `populate_youtube` | Index YouTube channel transcripts |
| `get_coverage` | Brief-vs-corpus coverage report |
| `get_coverage_explore` | Topic Explorer data with clusters |

### Growth & GSC

| Tool | Description |
|------|-------------|
| `get_growth_plan` | Get the cached growth plan for a site |
| `generate_growth_plan` | Generate a fresh growth plan |
| `gsc_sync` | Trigger a Search Console sync |
| `gsc_summary` | 28-day performance summary |
| `gsc_queries` | Top queries with metrics |
| `gsc_opportunities` | High-impression, low-position queries |
| `gsc_daily_summary` | Daily metrics for sparklines |
| `gsc_growing_queries` | Queries gaining performance |
| `gsc_declining_queries` | Queries losing performance |
| `gsc_growing_pages` | Pages gaining performance |
| `gsc_declining_pages` | Pages losing performance |

### WordPress

| Tool | Description |
|------|-------------|
| `get_wordpress_status` | Check connection status |
| `save_wordpress_credentials` | Connect WordPress (encrypted at rest) |
| `delete_wordpress_credentials` | Disconnect WordPress |

### Account, sites, pipeline

| Tool | Description |
|------|-------------|
| `get_account` | Account details, plan, usage, limits |
| `list_sites` | Your sites with source/brief counts |
| `create_site` | Add a new site |
| `update_site` | Update site name / URL |
| `delete_site` | Remove a site (cascades sources, briefs) |
| `update_site_schedule` | Set delivery frequency and hour |
| `list_account_emails` | Delivery email recipients |
| `add_account_email` | Add an email recipient |
| `delete_account_email` | Remove an email recipient |
| `get_profile` | Site voice profile |
| `trigger_profile` | Generate / refresh site profile |
| `trigger_ingestion` | Run source ingestion now |
| `trigger_synthesis` | Generate briefs from current content |
| `list_deliveries` | Email delivery history |

---

## Configuration reference

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `CMI_API_KEY` | Yes | — | Your API key from Dashboard → Account → API & MCP Server (starts with `cr_`) |
| `CMI_API_URL` | No | `https://api.contentmarketingideas.co` | API base URL — override only for self-hosted or staging |

---

## Security

Your API key authenticates as your account and your account only. Every request is server-side authenticated against `users.api_key` (hashed). The API enforces ownership checks on every resource: you cannot read, modify, or delete another user's data even by guessing IDs. No `X-User-ID` impersonation header exists.

If a key leaks, revoke it from **Dashboard → Account → API & MCP Server** and generate a new one — old keys are immediately rejected.

---

## Plans and limits

The MCP itself is free and open source. The platform behind it has tiered limits:

| Plan | Sources | Sites | Frequency | Articles / month |
|------|---------|-------|-----------|------------------|
| Free | 5 | 1 | Weekly | 0 |
| Pro | 25 | 1 | Daily | 10 |
| Business | 50 | 5 | Daily | 25 |
| Publisher | 100 | 10 | Daily | 50 |

Free is enough to wire up the MCP and try every tool against real data. Pro unlocks daily delivery, voice-matched drafts, growth plans, and keyword analytics. Business adds multi-site, WordPress publishing, and competitor intel. Pricing is at [contentmarketingideas.co/pricing](https://contentmarketingideas.co/pricing).

---

## Requirements

- Node.js 18+
- A Content Marketing Ideas account (free tier works) and an API key
- An MCP-compatible client: Claude Desktop, Claude Code, Cursor, Windsurf, or any other MCP host

---

## Links

- Product: [contentmarketingideas.co](https://contentmarketingideas.co)
- Why I built it: [houtini.com — Content Marketing Ideas: what it is, how I built it, and why I use it every day](https://houtini.com/content-marketing-ideas-what-it-is-how-i-built-it-and-why-i-use-it-every-day/)
- npm: [@houtini/contentmarketingideas](https://www.npmjs.com/package/@houtini/contentmarketingideas)
- MCP spec: [modelcontextprotocol.io](https://modelcontextprotocol.io/)

## Licence

MIT