MCP Storyblok Server

A comprehensive Model Context Protocol (MCP) server for Storyblok CMS integration. This server provides tools for managing stories, assets, components, releases, and more through a well-organized, modular architecture.

Features

- Story Management: CRUD operations, publishing, versioning, and lifecycle management
- Asset Management: Upload workflows, organization, and folder management
- Component Management: Block/component schema management and updates
- Tag Management: Organization and categorization of content
- Release Management: Scheduled publishing workflows
- Content Search: Advanced filtering and content discovery
- Space Management: Space-level operations and metadata

Architecture

The server follows a modular architecture with clear separation of concerns:

src/
├── config/           # Configuration and environment setup
├── types/            # TypeScript type definitions
├── utils/            # Shared utilities and API helpers
├── tools/            # Tool implementations organized by feature
│   ├── ping.ts       # Health check
│   ├── stories.ts    # Story management
│   ├── releases.ts   # Release workflows
│   ├── tags.ts       # Tag management
│   ├── assets.ts     # Asset management
│   ├── components.ts # Component management
│   ├── search.ts     # Content discovery
│   ├── space.ts      # Space operations
│   └── index.ts      # Tool registration
└── index.ts          # Main server entry point

Environment Variables

The following environment variables are required:

STORYBLOK_SPACE_ID=your_space_id
STORYBLOK_MANAGEMENT_TOKEN=your_management_token
STORYBLOK_DEFAULT_PUBLIC_TOKEN=your_public_token

Installation & Setup

1. Install dependencies:

yarn install

2. Build the project:

yarn build

3. Configure environment variables in your MCP client configuration.

Development

Building

yarn build

Type Checking

yarn tsc --noEmit

Tool Categories

Basic Tools

- ping: Server health check

Content Management

- fetch-stories: List stories with filtering - get-story: Get specific story by ID/slug - create-story: Create new stories - update-story: Update existing stories - delete-story: Delete stories - publish-story / unpublish-story: Publishing controls - get-story-versions / restore-story: Version management

Tag Management

- fetch-tags: List all tags - create-tag: Create new tags - create-tag-and-add-to-story: Create and assign tags - delete-tag: Remove tags

Release Management

- fetch-releases: List releases - create-release: Create scheduled releases - add-story-to-release: Add content to releases - publish-release: Publish releases - delete-release: Remove releases

Asset Management

- fetch-assets: List assets with filtering - get-asset: Get specific asset details - delete-asset: Remove assets - init-asset-upload / complete-asset-upload: Upload workflow - fetch-asset-folders: List asset folders - create-asset-folder / update-asset-folder / delete-asset-folder: Folder management

Component Management

- fetch-components: List all components - get-component: Get specific component - create-component: Create new components - update-component: Update component schemas - delete-component: Remove components

Content Discovery

- search-stories: Advanced content search - get-story-by-slug: Get content by slug

Space Management

- get-space: Get space information - fetch-folders: List content folders - fetch-datasources: List datasources

Best Practices Implemented

- Modular Architecture: Each tool category is in its own file
- Type Safety: Comprehensive TypeScript types for all interfaces
- Error Handling: Consistent error handling across all tools
- Code Reuse: Shared utilities for common operations
- Documentation: Comprehensive inline documentation
- Configuration Management: Centralized environment variable handling

API Coverage

This server provides comprehensive coverage of the Storyblok Management API and Content Delivery API, including:

- Stories API (Management & Delivery)
- Assets API
- Components API
- Releases API
- Tags API
- Space API
- Datasources API

Each tool includes proper error handling, parameter validation, and consistent response formatting.