CrewHero Marketing MCP Server

Model Context Protocol (MCP) server for CrewHero Marketing integration with Claude Desktop. Enables blog post management and LinkedIn content creation directly from Claude.

Features

Blog Management (6 tools)

• list_blog_posts - List posts with filters (status, tags, author)
• get_blog_post - Get full post by slug or ID
• create_blog_post - Create draft or published posts
• update_blog_post - Update existing posts
• publish_blog_post - Publish draft posts
• delete_blog_post - Archive posts

LinkedIn Management (2 tools)

• list_linkedin_posts - View drafts and scheduled posts
• create_linkedin_post - Create draft or scheduled posts

Reference Data (2 tools)

• list_tags - Get all tags with usage counts
• list_authors - Get blog authors

Prerequisites

1. CrewHero Marketing App running locally or deployed
2. API Key generated from the admin dashboard
3. Claude Desktop installed
4. Node.js 18+ installed

Installation

For End Users (Recommended)

See INSTALL.md for the complete user guide.

Quick setup using npm (no codebase access needed):

1. Generate API Key

1. Navigate to admin dashboard: http://localhost:3000/iddqd/api-keys
2. Click "Generate API Key"
3. Enter a name (e.g., "Claude Desktop - MacBook Pro")
4. Save the key immediately - it will only be shown once
5. Key format: ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Configure Claude Desktop

Edit your Claude Desktop configuration file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Add the MCP server configuration:

{
  "mcpServers": {
    "crewhero-marketing": {
      "command": "npx",
      "args": ["-y", "@crewhero/marketing-mcp-server"],
      "env": {
        "BASE_URL": "https://your-app-url.com",
        "CREWHERO_API_KEY": "ck_your_api_key_here"
      }
    }
  }
}

Important:

• Replace https://your-app-url.com with your actual app URL
• For local development: BASE_URL should be http://localhost:3000
• For production: Use your deployed URL (e.g., https://marketing.crewhero.com)
• Keep your API key secret - never commit it to version control

3. Restart Claude Desktop

Quit Claude Desktop completely and restart it. The MCP server will connect automatically.

For Developers (Manual Build)

If you're developing the MCP server or need to build from source:

1. Build the MCP Server

cd mcp-server
npm install
npm run build

2. Generate API Key

Same as above.

3. Configure Claude Desktop

Use the manual path configuration:

{
  "mcpServers": {
    "crewhero-marketing": {
      "command": "node",
      "args": ["/absolute/path/to/crewhero-marketing/mcp-server/dist/index.js"],
      "env": {
        "BASE_URL": "http://localhost:3000",
        "CREWHERO_API_KEY": "ck_your_api_key_here"
      }
    }
  }
}

Important:

• Use absolute paths (not ~ or relative paths)
• This method requires codebase access

4. Restart Claude Desktop

Quit Claude Desktop completely and restart it. The MCP server will connect automatically.

Verification

Test the connection:

1. Open Claude Desktop
2. Type: "List my blog posts"
3. Claude should call the list_blog_posts tool and return results

Usage Examples

Blog Post Creation

User: "Create a blog post about Next.js 15 Server Actions"

Claude:

• Researches the topic
• Calls create_blog_post with:
  • Title, slug, excerpt, content (markdown)
  • Status: draft
  • Tags: ["nextjs", "react", "server-actions"]
• Returns: "Created draft post with ID: xxx"

User: "Publish it"

Claude:

• Calls publish_blog_post with the ID
• Confirms: "Post published successfully"

LinkedIn Content

User: "Draft a LinkedIn post about that blog post for tomorrow at 9am"

Claude:

• Calls get_blog_post to get the content
• Generates LinkedIn-friendly summary
• Calls create_linkedin_post with:
  • Content (summarized)
  • Link URL to the blog post
  • Status: scheduled
  • Scheduled for: tomorrow 9am (ISO 8601 format)
• Confirms: "LinkedIn post scheduled"

Content Audit

User: "Show me all draft posts older than 30 days"

Claude:

• Calls list_blog_posts with status=draft
• Filters by date
• Lists posts with edit links

API Endpoints Used

The MCP server calls these Next.js API routes:

| Tool | Method | Endpoint | |------|--------|----------| | list_blog_posts | GET | /api/iddqd/blog-posts | | get_blog_post | GET | /api/iddqd/blog-posts/[id] | | create_blog_post | POST | /api/iddqd/blog-posts | | update_blog_post | PUT | /api/iddqd/blog-posts/[id] | | delete_blog_post | DELETE | /api/iddqd/blog-posts/[id] | | list_linkedin_posts | GET | /api/iddqd/linkedin/posts | | create_linkedin_post | POST | /api/iddqd/linkedin/posts | | list_tags | GET | /api/iddqd/tags | | list_authors | GET | /api/iddqd/authors |

All endpoints support both:

• Session authentication (cookies) - for web UI
• API key authentication (Bearer token) - for MCP

Security

API Key Best Practices

1. One key per device/user

   • Generate separate keys for each team member
   • Use descriptive names ("Alice's MacBook Pro")

2. Revoke compromised keys immediately

   • Admin dashboard → API Keys → Revoke
   • Applications using the key lose access instantly

3. Never commit keys to git

   • Keep keys in environment variables or config files
   • Add config files to .gitignore

4. Rotate keys periodically

   • Generate new key
   • Update Claude Desktop config
   • Revoke old key

How Authentication Works

1. MCP server sends API requests with Authorization: Bearer ck_xxx header
2. Combined auth middleware checks for API key:
   • Extracts key from header
   • Queries api_keys table
   • Compares bcrypt hash
   • Validates key is not revoked
   • Returns associated user
3. RLS policies automatically filter data by user
4. All actions are scoped to the authenticated user

Troubleshooting

MCP Server Won't Start

Error: BASE_URL and CREWHERO_API_KEY environment variables are required

Solution: Check Claude Desktop config has both variables set correctly.

Error: Connection refused

Solution: Ensure the Next.js app is running at the configured BASE_URL.

API Key Authentication Failed

Error: Invalid API key

Solutions:

1. Verify the key is copied correctly (no spaces/newlines)
2. Check the key hasn't been revoked
3. Ensure the key starts with ck_
4. Generate a new key if needed

Tools Not Appearing in Claude

1. Quit Claude Desktop completely (Cmd+Q on Mac)
2. Restart Claude Desktop
3. Check MCP server logs in Console.app (Mac) or Event Viewer (Windows)
4. Verify the server path in config is absolute and correct

"Blog post not found" Errors

• The MCP server user account may not have access to the post
• RLS policies filter data by user_id
• Ensure you're authenticated as the correct user

Development

Making Changes

1. Edit TypeScript source files in src/
2. Rebuild: npm run build
3. Restart Claude Desktop to load changes

Adding New Tools

1. Create tool implementation in src/tools/
2. Add tool definition to src/index.ts in tools array
3. Add handler in CallToolRequestSchema switch statement
4. Rebuild and test

Logging

MCP server logs to stderr (visible in Claude Desktop logs):

console.error('Debug message')

Find logs:

• macOS: Console.app → Filter for "Claude"
• Windows: Event Viewer

Architecture

┌─────────────────┐
│ Claude Desktop  │
└────────┬────────┘
         │ MCP Protocol (stdio)
         ▼
┌─────────────────────┐
│ MCP Server          │
│ (Node.js)           │
└────────┬────────────┘
         │ HTTP + API Key
         ▼
┌─────────────────────┐
│ Next.js API Routes  │
│ (/api/iddqd/*)      │
└────────┬────────────┘
         │ Combined Auth Middleware
         │ (Session OR API Key)
         ▼
┌─────────────────────┐
│ Supabase Database   │
│ (RLS Policies)      │
└─────────────────────┘

Support

For issues or questions:

1. Check this README
2. Review API endpoint implementation
3. Check Claude Desktop MCP logs
4. Verify API key is valid and not revoked

License

MIT