AI Integration & MCP Server - ContentMK Docs

ContentMK includes a built-in MCP (Model Context Protocol) server that lets AI tools like Claude Code, Cursor, and other MCP-compatible clients interact with your content data directly. Search articles, update statuses, create content ideas, check sync state, and review SEO data — all from within your AI workflow.

Prerequisites

Before connecting any AI tool, two things need to be in place:

1. ContentMK must be running. The MCP server communicates with the app’s local API, so the app needs to be started first (npm start from a terminal).
2. Build the MCP server. Run npm run mcp:build once. This compiles the server to dist/mcp-server.js. You only need to rebuild after ContentMK updates.

Setting Up Claude Code

Add the following to your Claude Code MCP configuration. This goes in ~/.claude.json for global access, or in a project-level .claude/settings.json if you prefer per-project config:

{
  "mcpServers": {
    "contentmk": {
      "command": "node",
      "args": ["dist/mcp-server.js"],
      "cwd": "/path/to/contentmk"
    }
  }
}

Replace /path/to/contentmk with the actual path to your ContentMK installation directory.

Once configured, Claude Code will automatically discover the MCP tools and resources listed below. You can verify the connection by asking Claude Code to list your sites or search your articles.

Setting Up Cursor

In Cursor’s settings, add an MCP server with the following values:

• Command: node
• Args: dist/mcp-server.js
• Working Directory: Your ContentMK installation path

The same tools and resources are available to Cursor as to Claude Code.

In-App Configuration

You don’t have to write the config by hand. Inside ContentMK, navigate to the AI Integration page (accessible from the sidebar when viewing All Sites). The MCP Configuration section includes the JSON snippet pre-filled with your actual installation path and a copy button for quick setup.

Available MCP Tools

The MCP server provides 13 tools that AI clients can call:

Tool	Description
get_health_summary	Application health overview — site count, article count, system status
search_articles	Full-text search across all articles, with optional site filter
list_articles	List articles with optional filtering by site and status
get_article	Retrieve full details for a single article by ID (content, metadata, health scores)
create_article	Create a new article (requires site_id, title, and url)
update_article	Update fields on an existing article (status, notes, categories, etc.)
delete_article	Permanently delete an article by ID
list_sites	List all configured sites
get_site_stats	Article counts and status breakdown for a specific site
get_sync_status	WordPress sync state for a site
get_seo_data	SEO metadata coverage statistics for a site
list_article_notes	List WordPress Notes for a specific article, with status filtering
list_article_files	List files stored in an article’s folder on disk

These tools give AI assistants read and write access to your content inventory. For example, you could ask Claude Code to “find all draft articles on my blog that haven’t been updated in 30 days” or “create a new article idea for the keyword cluster I’m working on.”

Available Resources

In addition to tools, the MCP server exposes four resources that AI clients can read directly:

Resource	URI
All sites	contentmk://sites
Site articles	contentmk://sites/{siteId}/articles
Site statistics	contentmk://sites/{siteId}/stats
App status	contentmk://status

Resources provide a read-only view of your data and are useful for AI tools that prefer to pull context rather than call tools.

Built-In AI Service

ContentMK also includes a built-in AI service that works on a BYOK (Bring Your Own Key) basis. You supply your own API key and ContentMK handles the rest.

Supported providers:

• Claude (Anthropic) — default model: claude-sonnet-4-20250514
• OpenAI — default model: gpt-4o

API keys are encrypted at rest in the local database. The UI only displays the last 4 characters of any stored key, so your credentials are never fully visible on screen. Configure your keys in the AI Integration page under AI Provider Settings.

Per-Site AI Access Control

By default, no sites are exposed to AI tools. This is an intentional opt-in design — you choose exactly which sites AI tools can see, keeping token usage focused and your data under control.

To manage access:

1. Open the AI Integration page from the All Sites sidebar
2. In the AI Site Access section, toggle individual sites on or off
3. Changes take effect immediately for new MCP tool calls

Only exposed sites appear in MCP tool results. If no sites are enabled, tools return empty results with a message pointing you to the settings page.

For power users and automated setups, the CONTENTMK_MCP_SITE_IDS environment variable overrides the database configuration. Set it to a comma-separated list of site IDs to control access without the UI.

Structured Exports

For AI tools that don’t support MCP, or when you want to feed data into a prompt manually, ContentMK can export site data as JSON or Markdown files optimized for AI workflows.

Available export types include:

• Article inventory — Full list of articles with metadata
• Health summary — Content health scores and status breakdown
• SEO overview — SEO metadata coverage across articles
• Content gaps — Areas where coverage is missing or thin

To export, navigate to a site’s Settings page and look for the Export for AI section. Choose your export type and format (JSON or Markdown), then copy or download the output. Exports are scoped to the site you’re currently viewing.

Troubleshooting

“Connection refused” errors: ContentMK must be running for the MCP server to work. Start the app with npm start before connecting AI tools.

“Command not found” errors: Make sure you’ve built the MCP server with npm run mcp:build first. The compiled output lives at dist/mcp-server.js.

Stale data: The MCP server reads live data from the local API with no caching layer. If data seems stale, verify that ContentMK is running and that any recent sync operations have completed.

No sites appearing in results: Check that you’ve enabled at least one site for AI access in the AI Integration page. The default is all sites hidden.