MCP Read Me

@cuppa-ai/mcp-server

Model Context Protocol (MCP) server for Cuppa AI. Gives AI clients (Cursor, Claude Desktop, Windsurf, etc.) full access to Cuppa’s content generation, SEO optimization, and brand management capabilities.

Quick Start

1. Get your API key

Go to Cuppa Settings > API Keys and create a key.

2. Configure your MCP client

Cursor (.cursor/mcp.json in your project or global config):

{
  "mcpServers": {
    "cuppa": {
      "command": "npx",
      "args": ["-y", "@cuppa-ai/mcp-server"],
      "env": {
        "CUPPA_API_KEY": "cpa-your-key-here"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cuppa": {
      "command": "npx",
      "args": ["-y", "@cuppa-ai/mcp-server"],
      "env": {
        "CUPPA_API_KEY": "cpa-your-key-here"
      }
    }
  }
}

Windsurf / Cline / other MCP clients: Same pattern. Point to npx -y @cuppa-ai/mcp-server with CUPPA_API_KEY env var.

Available Tools (75+)

Content Creation (10 tools)

Tool	Description
`create_content`	Generate an AI article from a keyword
`get_content_status`	Poll article generation progress
`get_content`	Retrieve generated article (paginated HTML)
`export_content`	Get full article HTML without truncation
`update_content`	Update title, content, meta, or target keyword
`list_contents`	List articles with filters
`delete_content`	Delete an article
`publish_content`	Push to connected CMS
`import_content`	Import an article from a URL
`parse_brief`	Parse a content brief into generation parameters

Content Grading & SERP (5 tools)

Tool	Description
`grade_content`	Trigger SEO/readability grading
`get_content_grade`	Get grading results
`fetch_serp_data`	Trigger SERP competitor analysis
`get_serp_data`	Get SERP analysis results
`optimize_content`	Get AI optimization suggestions

Projects / Bulk Generation (4 tools)

Tool	Description
`create_project`	Create bulk generation project
`list_projects`	List projects
`get_project`	Get project details
`export_project`	Export project articles

Research (4 tools)

Tool	Description
`research_keywords`	Keyword research from seed terms
`research_serp`	SERP analysis for a keyword
`research_competitors`	Competitor content analysis
`research_cluster`	Topic cluster research

Images (2 tools)

Tool	Description
`generate_image`	Generate an AI image
`generate_images_bulk`	Bulk image generation for articles

Brand & Knowledge (7 tools)

Tool	Description
`get_brand`	Get Brand DNA for a site
`update_brand_context`	Update brand context fields
`update_brand_visual_style`	Update colors, fonts, logo
`get_notebook`	List client notes / meeting transcripts
`list_knowledge`	List knowledge sources
`create_knowledge`	Create text knowledge source
`get_knowledge`	Get knowledge source details

Presets / AI Instructions (5 tools)

Tool	Description
`list_presets`	List writing presets
`get_preset`	Get preset details
`create_preset`	Create a preset
`update_preset`	Update a preset
`delete_preset`	Delete a preset

Templates (2 tools)

Tool	Description
`list_templates`	List custom templates
`get_template`	Get template details

Clusters (5 tools)

Tool	Description
`generate_cluster`	Generate topic cluster
`list_clusters`	List clusters
`get_cluster`	Get cluster details
`activate_cluster`	Add cluster to plan
`deactivate_cluster`	Remove from plan

Content Planner & Strategy (7 tools)

Tool	Description
`list_planner`	List planner items
`create_planner_item`	Add to content plan
`update_planner_item`	Update planner item
`delete_planner_item`	Remove planner item
`get_content_calendar`	Unified calendar (articles + local + social)
`get_content_strategy`	Get site content strategy settings
`update_content_strategy`	Update article defaults, social, newsletter, etc.

Performance Hub (4 tools)

Tool	Description
`get_brand_performance`	KPIs, visibility score, and quick wins from Performance Hub
`get_content_health`	Top pages, content decay, striking distance, cannibalization
`get_ai_visibility`	LLM mentions, top prompts, cited pages, citation gaps
`get_backlinks`	Domain rating, backlink stats, referring domains (via Ahrefs)

Newsletters (3 tools)

Tool	Description
`list_newsletters`	List generated newsletters for a site
`get_newsletter`	Get newsletter details with full content and HTML
`generate_newsletter`	Generate weekly newsletter from published articles

Tool	Description
`generate_social`	Generate social post (from article OR standalone topic)
`generate_social_multi`	Multi-platform post generation
`publish_social`	Publish to platform immediately
`schedule_social`	Schedule a post for future publishing
`list_social_platforms`	List connected platforms with best practices
`list_social_posts`	List social posts with filters
`get_social_post`	Get social post details (with analytics)
`update_social_post`	Update draft/scheduled post
`delete_social_post`	Delete draft/scheduled post
`get_social_analytics`	Live social analytics: impressions, engagements, reach, followers, best posting times, content decay, top posts with links
`generate_carousel`	Generate LinkedIn carousel slides
`publish_carousel`	Publish carousel to LinkedIn

Sites & GSC (3 tools)

Tool	Description
`list_sites`	List sites/brands
`create_site`	Create a new site
`get_gsc_queries`	Get Search Console data

Research Agents (3 tools)

Tool	Description
`list_agents`	List research agents
`get_agent`	Get agent with latest results
`trigger_agent_run`	Trigger manual agent run

Links (6 tools)

Tool	Description
`get_link_stats`	Link Engine stats
`get_link_categories`	List link categories
`delete_link_category`	Delete a link category
`list_link_sites`	List sites in Link Engine
`update_link_site`	Update link site config
`bulk_update_link_sites`	Bulk update link site settings
`refresh_link_sitemaps`	Refresh sitemap indexes

Meta & Models (3 tools)

Tool	Description
`list_models`	Available text models
`list_image_models`	Available image models
`chat`	Brand-aware chat completion

MCP Resources

In addition to tools, the server exposes MCP resources that can be fetched directly to disk without entering the AI context window:

Resource URI	MIME Type	Description
`cuppa://content/\{articleId\}`	`text/html`	Full article HTML. Use with `FetchMcpResource` + `downloadPath` to save.

Cursor example (saves full HTML to disk, no truncation):

FetchMcpResource({
  server: "cuppa",
  uri: "cuppa://content/<article-id>",
  downloadPath: "content/blog/my-article.html"
})

Environment Variables

Variable	Required	Description
`CUPPA_API_KEY`	Yes	Your Cuppa API key (starts with `cpa-`)
`CUPPA_API_URL`	No	Override API base URL (default: `https://api.cuppa.ai`)

Plan Requirements

Some tools require specific plan tiers:

Feature	Minimum Plan
Content generation, images	All plans
Knowledge sources	Power
Custom templates	Business
Research agents	Power
Link Engine	Business
Brand Notebook	Agency

Development

# Install dependencies
npm install
 
# Build
npm run build
 
# Run locally
CUPPA_API_KEY=cpa-xxx node dist/bin/cli.js

License

MIT

MCP Server API, MCP or CLI