Journey / SameUp CMS MCP Server

A Model Context Protocol (MCP) server developed for Journey / SameUp CMS. It enables AI assistants (Claude Desktop, Cursor, Antigravity, etc.) to manage components and pages by talking directly to the CMS REST API.

Features

• Modern TypeScript & MCP SDK: Type-safe tools based on @modelcontextprotocol/sdk and zod.

• Automatic Authentication: Automatically logs in to the CMS API (/api/v1/login), stores the returned auth cookie (at), and automatically refreshes it when it expires.

• Local Development Compatible: Automatically tolerates self-signed SSL certificates (CMS_IGNORE_SSL=true).

Installation & Running

1. Installing Dependencies

pnpm install

2. Environment Variables (.env)

Configure the .env file in the root directory:

CMS_API_URL=https://api-journey.sameup.dev
CMS_EMAIL=your-admin-email@sameup.co
CMS_PASSWORD=your-secure-password
CMS_IGNORE_SSL=true

3. Building and Starting

# Projeyi derle
pnpm run build

# Doğrudan derlenmiş dosyayı çalıştır
pnpm start

# Geliştirme modu (Hot reload)
pnpm run dev

Available MCP Tools

1. list_components

Lists all active components defined in SameUp CMS (Custom, SingleLine, Markdown, Photo, Dropdown, etc.).

Parameters:

• search (string, optional): Filter by component title or slug (e.g., "banner", "markdown").

• type (string, optional): Filter by component type (e.g., "Custom", "SingleLine", "Markdown").

• includeDetails (boolean, optional, default: false): When set to true, also fetches the child fields (children) of Custom components.

2. get_component_detail

Fetches all properties of a specific component by its ID or Slug, and if it is of type Custom, also retrieves its child components (children) hierarchically.

Parameters:

• id (number, optional): The numeric ID of the component (e.g., 1, 25).

• slug (string, optional): The slug name of the component (e.g., "announcements", "app-banner"). (Note: At least one of the id or slug fields must be provided).

3. create_component

Defines a new component template on the CMS. In a single call, both a Custom parent component and its associated children fields can be created.

Parameters:

• title (string, required): The name of the component (e.g., "Hero Banner", "Feature Card").

• slug (string, required): The unique slug matching the front-end (e.g., "hero-banner", "feature-card").

• componentType (string, required): "Custom", "SingleLine", "Markdown", "Photo", "Document", "Dropdown", "Video", "Form", "FormItem", "List".

• canBeRepeated (boolean, optional, default: false): Is it a repeatable list?

• reusable (boolean, optional, default: true): Is it reusable?

• data (string, optional): Default data/text.

• parentId (number, optional): The parent component ID if it will be added under an existing parent component.

• children (array, optional): List of child fields for Custom components (title, slug, componentType, canBeRepeated, reusable, data).

IDE / MCP Client Configuration

Claude Desktop / Cursor / Antigravity Config

You can add the following block to your mcp_config.json or claude_desktop_config.json file:

{
  "mcpServers": {
    "journey-cms": {
      "command": "node",
      "args": [
        "/path/to/journey-mcp/dist/index.js"
      ],
      "env": {
        "CMS_API_URL": "https://api-journey.sameup.dev",
        "CMS_EMAIL": "your-admin-email@sameup.co",
        "CMS_PASSWORD": "your-secure-password",
        "CMS_IGNORE_SSL": "true"
      }
    }
  }
}