Chapter 1: MCP Server Installation

Copied to clipboard!

Estimated Time: 15-20 minutes Difficulty: Beginner Prerequisites: Claude Code CLI available

📖 What You'll Learn

By the end of this chapter, you will:

✅ Understand what MCP servers are and why they matter
✅ Successfully install the Vibe CMS MCP server
✅ Configure authentication with your Vibe CMS project
✅ Verify the installation is working correctly
✅ Troubleshoot common installation issues

🎯 Overview

What is MCP?

MCP (Model Context Protocol) is a standardized protocol that allows Claude Code to interact with external tools and services. Think of it as a bridge that connects Claude to your Vibe CMS project.

Why MCP for Vibe CMS?

🤖 AI-Native: Work with content using natural language
⚡ Fast: Direct API access without manual operations
🔒 Secure: Scoped access with API authentication
🎯 Context-Aware: Claude understands your content structure

What is the Vibe CMS MCP Server?

The Vibe CMS MCP server provides Claude Code with tools to:

Query and list collections
Create and manage content items
Upload and organize files
Handle translations and locales
Update field schemas
Perform content operations

Real-world example: Instead of manually:

Opening your CMS dashboard
Clicking through menus
Filling out forms
Uploading files one by one

You can simply tell Claude:

"Create a blog post collection with title, content, author, and featured image fields, then add 3 sample posts in English and German"

And Claude will handle it all using the MCP server!

📢 Important Note: Claude Desktop vs Claude Code

⚠️ KNOWN ISSUE / FUTURE FEATURE:

This guide currently covers MCP server installation for Claude Code (the CLI/API version). If you have Claude Desktop (the desktop application) installed, you can also add Vibe CMS MCP to it using a similar configuration approach.

Status: 📋 Documentation Pending

The Claude Desktop MCP installation guide will be added in a future update. The configuration process is similar but uses a different config file location:

Claude Code: Project-specific .mcp.json files
Claude Desktop: ~/.config/claude/claude_desktop_config.json (global configuration)

For now: This guide focuses on Claude Code integration. Claude Desktop instructions coming soon!

✅ Prerequisites Checklist

Before starting, ensure you have:

Claude Code or Claude Desktop App installed (version 1.0.0 or higher)
- Claude Code: Part of your development environment
- Claude Desktop: Download from https://claude.ai/download
Vibe CMS Project created
- Sign up at: https://vibecms.com (if applicable)
- Note your Project ID
API Token generated for your project
- Found in: Project Settings → API Keys
Text Editor for editing JSON files
- VS Code, Sublime Text, or any text editor
Terminal Access (macOS/Linux) or Command Prompt (Windows)

💡 TIP: Have your Project ID and API Token ready - you'll need them during configuration!

📥 Installation Methods

There are three ways to install the Vibe CMS MCP server:

Method 1: NPX (Recommended for Most Users)

Best for: Quick setup without manual installation Pros: Automatic updates, minimal configuration Cons: Requires Node.js installed

Method 2: Global NPM Install

Best for: Users who want a permanent installation Pros: Faster startup, works offline after install Cons: Manual updates required

Method 3: Local Development Setup

Best for: Developers contributing to Vibe CMS Pros: Full source code access, easy debugging Cons: More complex setup

For this guide, we'll use Method 1 (NPX) - it's the most straightforward and recommended approach.

🚀 Step-by-Step Installation

Step 1: Locate Claude Configuration File

The Claude Code CLI stores its MCP server configuration in a JSON file. The location depends on your project:

macOS/Linux:

project-root/.mcp.json

Windows:

project-root\.mcp.json

💡 TIP: If the file doesn't exist, create it! It's normal for new installations.

Step 2: Open Configuration File

Option A: Using Terminal (macOS/Linux)

# Navigate to your project directory
cd /path/to/your/project

# Open with your default text editor
open .mcp.json

# Or use a specific editor
code .mcp.json  # VS Code
nano .mcp.json  # Nano

Option B: Using File Explorer (Windows)

# Navigate to your project directory
cd C:\path\to\your\project

# Open with Notepad
notepad .mcp.json

Option C: Manual Navigation

Open your file manager
Navigate to your project root directory
Right-click the file → Open with your preferred editor

Step 3: Add Vibe CMS MCP Server Configuration

Copy the following configuration into your .mcp.json file:

{
  "mcpServers": {
    "vibe-cms-prod": {
      "command": "npx",
      "args": [
        "-y",
        "vibe-cms-mcp-server"
      ],
      "env": {
        "VIBE_PROJECT_ID": "your-project-id-here",
        "VIBE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

⚠️ IMPORTANT: Replace the placeholder values:

your-project-id-here → Your actual Vibe CMS project ID
your-api-token-here → Your actual API token

Step 4: Get Your Credentials

Finding Your Project ID

Log in to your Vibe CMS dashboard
Navigate to Project Settings
Look for Project ID (usually at the top)
Copy the value (format: proj_abc123xyz)

Example: proj_67890abcdef12345

Generating an API Token

In Vibe CMS dashboard, go to Settings → API Keys
Click "Generate New Token"
Give it a name (e.g., "Claude MCP Access")
Select permissions:
- ✅ Read content
- ✅ Write content
- ✅ Manage files
- ✅ Manage schema
Click "Generate"
Copy the token immediately - you won't see it again!

🔒 SECURITY NOTE:

Treat API tokens like passwords
Never commit them to version control
Store them securely (password manager recommended)
Rotate tokens periodically

Step 5: Complete Configuration Example

Here's what your final configuration should look like:

{
  "mcpServers": {
    "vibe-cms-prod": {
      "command": "npx",
      "args": [
        "-y",
        "vibe-cms-mcp-server"
      ],
      "env": {
        "VIBE_PROJECT_ID": "proj_67890abcdef12345",
        "VIBE_API_TOKEN": "vibe_token_abcdef123456789xyz"
      }
    }
  }
}

Configuration Options Explained

Field	Description	Required
`mcpServers`	Container for all MCP server configurations	✅ Yes
`vibe-cms-prod`	Server name (can be customized)	✅ Yes
`command`	Execution command (npx, node, etc.)	✅ Yes
`args`	Arguments passed to command	✅ Yes
`env`	Environment variables	✅ Yes
`VIBE_PROJECT_ID`	Your Vibe CMS project identifier	✅ Yes
`VIBE_API_TOKEN`	Authentication token for API access	✅ Yes

Working with Multiple Vibe CMS Projects

💡 IMPORTANT: You can configure multiple Vibe CMS MCP servers to work with different projects simultaneously!

Common use cases:

Production vs. Staging environments
Different websites (e.g., main site + documentation site)
Multiple client projects
Personal vs. Team projects

How to add multiple projects:

Step 1: Create a new project in Vibe CMS

Log in to vibecms.ai
Click "New Project" in the dashboard
Give it a name (e.g., "Documentation Site", "Staging Environment")
Note the new Project ID

Step 2: Generate an API token for the new project

Open the new project in Vibe CMS
Go to Settings → API Keys
Click "Generate New Token"
Select appropriate permissions
Copy the token immediately

Step 3: Add to your Claude configuration

Each project gets its own entry with a unique name and credentials:

{
  "mcpServers": {
    "vibe-cms-prod": {
      "command": "npx",
      "args": ["-y", "vibe-cms-mcp-server"],
      "env": {
        "VIBE_PROJECT_ID": "proj_production_id",
        "VIBE_API_TOKEN": "vibe_token_production_xxx"
      }
    },
    "vibe-cms-docs": {
      "command": "npx",
      "args": ["-y", "vibe-cms-mcp-server"],
      "env": {
        "VIBE_PROJECT_ID": "proj_docs_id",
        "VIBE_API_TOKEN": "vibe_token_docs_xxx"
      }
    },
    "vibe-cms-staging": {
      "command": "npx",
      "args": ["-y", "vibe-cms-mcp-server"],
      "env": {
        "VIBE_PROJECT_ID": "proj_staging_id",
        "VIBE_API_TOKEN": "vibe_token_staging_xxx"
      }
    }
  }
}

Step 4: Use specific servers in Claude

When working with Claude, specify which server to use:

"Using vibe-cms-prod, show me all collections"

"In vibe-cms-docs, create a user guide collection"

"With vibe-cms-staging, upload this test image"

Best practices for multiple projects:

✅ Use descriptive server names (vibe-cms-docs, vibe-cms-client-acme)
✅ Keep production and staging separate
✅ Use different API tokens for each project
✅ Document which server is for which purpose
✅ Rotate tokens independently

⚠️ Important: Each MCP server name must be unique, and each should have its own Project ID and API Token from different Vibe CMS projects.

Step 6: Save and Validate Configuration

Save the file (Ctrl+S or Cmd+S)
Validate JSON syntax using an online validator:
- https://jsonlint.com
- Copy your config and paste it in
- Fix any syntax errors reported

Common JSON errors to watch for:

❌ Missing commas between entries
❌ Extra commas after last entry
❌ Missing quotes around strings
❌ Unclosed brackets { or }

✅ Valid JSON example:

{
  "key": "value",
  "another": "value"
}

❌ Invalid JSON examples:

{
  "key": "value"
  "another": "value"  // Missing comma!
}

{
  "key": "value",
  "another": "value",  // Extra comma!
}

Step 7: Reload Claude Code Window

For changes to take effect:

All Platforms:

# Reload the window in Claude Code
# Use the command palette or restart your session

💡 TIP: In Claude Code, you can reload the window to pick up configuration changes without fully restarting the application.

✓ Verification

Quick Test: Check MCP Server Status

Open Claude Code
Start a new conversation
Type: "List all MCP servers"
Claude should respond with a list including vibe-cms-prod

Functional Test: Query Vibe CMS

Try this simple command:

"Show me all collections in my Vibe CMS project"

Expected response: Claude will list your collections (or confirm there are none if it's a new project)

Detailed Verification Checklist

Claude Code opens without errors
No MCP connection errors in Claude's status
Claude recognizes Vibe CMS tools when asked
Can successfully query collections
Can fetch project information

🐛 Troubleshooting

Issue 1: "MCP Server Not Found"

Symptoms: Claude doesn't recognize Vibe CMS tools

Possible Causes & Solutions:

Configuration file not loaded
- ✅ Verify file location is correct (project root)
- ✅ Check file name is exactly .mcp.json
- ✅ Ensure file has .json extension (not .json.txt)
Claude not reloaded
- ✅ Reload the window in Claude Code
- ✅ Restart your Claude Code session if needed
JSON syntax error
- ✅ Validate JSON at https://jsonlint.com
- ✅ Check for missing/extra commas
- ✅ Verify all brackets are closed

How to diagnose:

# Check if config file exists (macOS/Linux)
ls -la .mcp.json

# View file contents
cat .mcp.json

# Validate JSON syntax (if jq installed)
cat .mcp.json | jq .

Issue 2: "Authentication Failed"

Symptoms: Claude finds the server but can't access Vibe CMS

Possible Causes & Solutions:

Invalid API token
- ✅ Verify token was copied completely (no extra spaces)
- ✅ Check token hasn't expired
- ✅ Generate a new token if needed
Wrong Project ID
- ✅ Confirm Project ID in Vibe CMS dashboard
- ✅ Ensure no typos or extra characters
Insufficient permissions
- ✅ Check token has required permissions:
  - Read content
  - Write content
  - Manage files
  - Manage schema

How to test:

# Test API access directly (replace with your credentials)
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://api.vibecms.com/v1/projects/YOUR_PROJECT_ID

Expected: JSON response with project details If error: Check credentials and permissions

Issue 3: "NPX Command Not Found"

Symptoms: Error about npx not being available

Possible Causes & Solutions:

Node.js not installed
- ✅ Install Node.js from https://nodejs.org
- ✅ Recommended: Use LTS (Long Term Support) version
- ✅ Verify installation: node --version
NPX not in PATH
- ✅ Check PATH includes Node.js binaries
- ✅ Try full path to npx: /usr/local/bin/npx

How to diagnose:

# Check Node.js installation
node --version
npm --version
npx --version

# Find npx location
which npx

Alternative solution: Use global install method instead:

npm install -g vibe-cms-mcp-server

Then update config to:

{
  "command": "vibe-cms-mcp-server",
  "args": []
}

Issue 4: "Connection Timeout"

Symptoms: Requests to Vibe CMS hang or timeout

Possible Causes & Solutions:

Network connectivity
- ✅ Check internet connection
- ✅ Try accessing https://vibecms.com in browser
- ✅ Check firewall/proxy settings
Vibe CMS API issues
- ✅ Check Vibe CMS status page
- ✅ Try again in a few minutes
- ✅ Contact support if persistent
Rate limiting
- ✅ Wait a few minutes between requests
- ✅ Check API usage in dashboard
- ✅ Upgrade plan if hitting limits

Issue 5: "Unexpected Token" or JSON Errors

Symptoms: Claude reports configuration errors on startup

Possible Causes & Solutions:

Invalid JSON syntax
- ✅ Use JSON validator: https://jsonlint.com
- ✅ Check for smart quotes ("" vs "")
- ✅ Verify all strings are in double quotes
Copy-paste issues
- ✅ Copy from raw text, not formatted docs
- ✅ Remove any extra characters
- ✅ Type manually if issues persist

Common JSON pitfalls:

// ❌ WRONG: Single quotes
{
  'key': 'value'
}

// ✅ CORRECT: Double quotes
{
  "key": "value"
}

// ❌ WRONG: Comments in JSON
{
  "key": "value" // This breaks JSON!
}

// ✅ CORRECT: No comments
{
  "key": "value"
}

// ❌ WRONG: Trailing comma
{
  "key": "value",
}

// ✅ CORRECT: No trailing comma
{
  "key": "value"
}

Issue 6: "Permission Denied"

Symptoms: Can't save configuration file

Possible Causes & Solutions:

File permissions

# macOS/Linux: Fix permissions
chmod 644 .mcp.json

# Check permissions
ls -la .mcp.json

Running as wrong user
- ✅ Don't use sudo to edit project config
- ✅ Edit as your normal user account

Issue 7: MCP Server Crashes

Symptoms: Server starts but immediately stops

Possible Causes & Solutions:

Check Claude logs
- Look for error messages in Claude Code output
- Check terminal/console for diagnostic information
Version compatibility
- ✅ Update Claude Code to latest version
- ✅ Clear NPX cache: npx clear-npx-cache
- ✅ Try specifying version: npx -y vibe-cms-mcp-server@latest
Conflicting installations
- ✅ Remove global installs: npm uninstall -g vibe-cms-mcp-server
- ✅ Use only NPX method

Getting Help

If you're still experiencing issues:

Check Logs
- Claude Code console output
- Terminal output when starting Claude
Gather Information
- Operating system and version
- Claude Code version
- Node.js version (node --version)
- Full error messages
Contact Support
- GitHub Issues: https://github.com/vibecms/mcp-server/issues
- Email: support@vibecms.com
- Discord: https://discord.gg/vibecms

When reporting issues, include:

Steps to reproduce the problem
Expected vs actual behavior
Relevant log excerpts (redact API tokens!)
System information

🎓 Understanding the Configuration

Environment Variables Deep Dive

The env section passes environment variables to the MCP server process. These are like settings that tell the server how to connect to your Vibe CMS project.

Required Variables:

"env": {
  "VIBE_PROJECT_ID": "proj_xxx",  // Identifies which project
  "VIBE_API_TOKEN": "vibe_xxx"     // Authenticates requests
}

Optional Variables (advanced use cases):

"env": {
  "VIBE_PROJECT_ID": "proj_xxx",
  "VIBE_API_TOKEN": "vibe_xxx",
  "VIBE_API_URL": "https://custom-api.example.com",  // Custom API endpoint
  "VIBE_TIMEOUT": "30000",                            // Request timeout (ms)
  "VIBE_DEBUG": "true"                                // Enable debug logging
}

💡 TIP: For most users, only VIBE_PROJECT_ID and VIBE_API_TOKEN are needed!

Command and Args Explanation

"command": "npx",
"args": ["-y", "vibe-cms-mcp-server"]

Breaking this down:

command: The executable to run (npx)
args: Arguments passed to the command
- -y: Auto-approve prompts (don't ask "install package?")
- vibe-cms-mcp-server: Package name to execute

Alternative configurations:

Global installation:

"command": "vibe-cms-mcp-server",
"args": []

Specific version:

"command": "npx",
"args": ["-y", "vibe-cms-mcp-server@0.2.1"]

Local development:

"command": "node",
"args": ["/path/to/local/vibe-cms-mcp-server/dist/index.js"]

🎯 Best Practices

Security

Protect Your API Token
- ✅ Never share tokens publicly
- ✅ Use environment-specific tokens (prod vs. staging)
- ✅ Rotate tokens every 90 days
- ✅ Revoke tokens immediately if compromised
Principle of Least Privilege
- ✅ Grant only necessary permissions
- ✅ Create separate tokens for different purposes
- ✅ Use read-only tokens where write access isn't needed
Secure Configuration Storage
- ✅ Keep config file permissions restricted
- ✅ Don't commit config to version control
- ✅ Use secret management tools for teams

Organization

Naming Conventions

{
  "mcpServers": {
    "vibe-cms-prod": { /* ... */ },
    "vibe-cms-staging": { /* ... */ },
    "vibe-cms-dev": { /* ... */ }
  }
}

Documentation
- Add comments in a separate README (JSON doesn't allow comments)
- Document which projects each server connects to
- Note token generation dates for rotation tracking
Version Control
- Create a template config without sensitive data
- Share template with team
- Each developer adds their own credentials locally

Maintenance

Regular Updates

# Check for updates
npm view vibe-cms-mcp-server version

# Update (if globally installed)
npm update -g vibe-cms-mcp-server

# NPX automatically uses latest unless pinned

Health Checks
- Periodically verify MCP server is responding
- Test with simple queries
- Monitor for deprecation warnings

Backup Configuration

# Create backup before changes
cp .mcp.json .mcp.json.backup

✅ Verification Checklist

Before moving to Chapter 2, confirm:

Configuration file created and saved
Project ID and API Token correctly set
JSON syntax is valid
Claude Code window reloaded
MCP server appears in Claude's available tools
Can query collections successfully
No error messages in Claude
Understand how to troubleshoot common issues
Know where to get help if needed

📚 What's Next?

Congratulations! You've successfully installed and configured the Vibe CMS MCP server.

In Chapter 2, you'll learn:

Creating your first collection
Adding content with translations
Managing files and media
Understanding the content workflow

Recommended next steps:

✅ Test the installation thoroughly
✅ Bookmark this chapter for troubleshooting reference
✅ Familiarize yourself with Claude Code basics
✅ Move on to Chapter 2: First Steps with Vibe CMS

🎓 Key Takeaways

After completing this chapter, you should understand:

MCP bridges Claude and Vibe CMS - enabling natural language content management
Configuration is JSON-based - stored in project root as .mcp.json
Authentication requires two pieces - Project ID and API Token
NPX is the recommended method - simplest setup with automatic updates
Troubleshooting is systematic - check configs, credentials, and connectivity in order

📖 Additional Resources

MCP Protocol Documentation: https://modelcontextprotocol.io
Vibe CMS API Reference: https://docs.vibecms.com/api
Claude Code Help: https://claude.ai/help
Community Forum: https://community.vibecms.com
Video Tutorial: Watch MCP Setup Guide

💬 Feedback

Help us improve this chapter! Send feedback to:

📧 Email: docs@vibecms.com
💬 Discord: #documentation channel
🐛 GitHub: Open an issue
📝 Google Form: Chapter 1 Feedback Survey

Ready to start working with content? → Continue to Chapter 2: First Steps

Chapter 1 - MCP Server Installation | Vibe CMS User Manual v1.0