BlocksWeb MCP Server

Model Context Protocol server for BlocksWeb CMS - enables Claude Code integration.

What is this?

This package provides a Model Context Protocol (MCP) server that allows Claude Code to interact directly with your BlocksWeb CMS. It exposes all BlocksWeb API functionality as tools that Claude can use to:

• Create, read, update, and delete pages
• Manage collections and records
• Query data with advanced filtering
• Access workspace information

Installation

Option 1: Project-level (Recommended for teams)

Add to your project's .claude/config.json:

{
  "mcpServers": {
    "blocksweb": {
      "command": "npx",
      "args": ["-y", "@blocksweb/mcp-server"],
      "env": {
        "BLOCKSWEB_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 2: User-level

Use the BlocksWeb CLI to configure automatically:

npx @blocksweb/cli mcp install

This will add the MCP server to your Claude Code configuration.

Available Tools

The MCP server provides 14 tools:

Workspace

• get_workspace - Get workspace information and usage stats

Pages

• list_pages - List all pages (with optional search)
• get_page - Get page details by ID
• create_page - Create a new page
• update_page - Update an existing page draft (name, slug, content, SEO)
• delete_page - Delete a page

Collections

• list_collections - List all collections
• get_collection - Get collection schema
• create_collection - Create a new collection

Records

• list_records - List all records in a collection
• get_record - Get a specific record
• create_record - Create a new record
• delete_record - Delete a record
• query_records - Advanced querying with filters, sorting, pagination

Page Updates

The update_page tool updates the draft version of a page using the /draft endpoint. This supports:

• ✅ Updating page name
• ✅ Updating slug (auto-generated from name if not provided)
• ✅ Updating content blocks
• ✅ Updating SEO metadata (title, description, keywords)
• ✅ Partial updates (only send fields you want to change)

Note: Record updates are not currently supported by the API.

Environment Variables

• BLOCKSWEB_API_KEY - Your BlocksWeb API key (required)
• BLOCKSWEB_API_URL - API URL (optional, defaults to https://cloud.blocksweb.nl/api)

Authentication

API Key (Current Method)

⚠️ Note: Device Code Flow is temporarily disabled while backend endpoints are being deployed.

1. Log in to BlocksWeb Dashboard
2. Navigate to Settings > API Keys
3. Create a new API key or copy an existing one
4. Set the BLOCKSWEB_API_KEY environment variable

Usage Example

Once configured, you can use Claude Code to interact with your CMS:

You: "List all pages in my BlocksWeb workspace"
Claude: [Uses list_pages tool to fetch pages]

You: "Create a new page called 'About Us' with slug 'about'"
Claude: [Uses create_page tool to create the page]

You: "Show me all blog posts published this month"
Claude: [Uses query_records tool with date filters]

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run locally
BLOCKSWEB_API_KEY=your-key node dist/index.js

Architecture

The MCP server uses:

• Transport: stdio (standard input/output)
• Protocol: Model Context Protocol v0.5.0
• API Client: Full BlocksWeb API v1 implementation
• Error Handling: Graceful error responses with detailed messages

Links

• BlocksWeb Documentation
• Model Context Protocol
• Claude Code

License

MIT