Marble MCP Server - Marble Documentation

Use Marble’s Model Context Protocol server to let AI agents read and manage content in your workspace through the Marble API.

You need a Marble API key. Write tools such as create, update, and delete require a private API key.

Installation

The quickest way to add Marble to supported MCP clients is with the add-mcp CLI.

npx add-mcp https://mcp.marblecms.com/mcp \
  --header "Mcp-Marble-Api-Key: $MCP_MARBLE_API_KEY" \
  -g

This installs Marble globally for the agents you select. Without -g, add-mcp writes project-level MCP config.

Cursor
VS Code
Claude Code
Codex
Manual

https://mintcdn.com/marblecms/HeUo3qaHbsCXRx9S/images/cursor.svg?fit=max&auto=format&n=HeUo3qaHbsCXRx9S&q=85&s=769b72a204a886e8872602f37e6e5f6a

Install in Cursor

Open Cursor with the Marble MCP server pre-filled.

Open the installer

Click Install in Cursor and allow your browser to open Cursor.

Add your API key

Cursor installs the server with this header:

Mcp-Marble-Api-Key: ${MCP_MARBLE_API_KEY}

Set MCP_MARBLE_API_KEY in your environment before starting Cursor.

Verify the connection

Open Cursor’s MCP settings and confirm that the marble server is enabled. The server URL should end with /mcp.

You can also add the server manually in Cursor:

{
  "mcpServers": {
    "marble": {
      "type": "streamableHttp",
      "url": "https://mcp.marblecms.com/mcp",
      "headers": {
        "Mcp-Marble-Api-Key": "${MCP_MARBLE_API_KEY}"
      }
    }
  }
}

https://mintcdn.com/marblecms/HeUo3qaHbsCXRx9S/images/vscode.svg?fit=max&auto=format&n=HeUo3qaHbsCXRx9S&q=85&s=a339d3a61b277b1273c92111db2fc538

Install in VS Code

Open VS Code with the Marble MCP server pre-filled.

Open the installer

Click Install in VS Code and allow your browser to open VS Code.

Add your API key

Set MCP_MARBLE_API_KEY in your environment before starting VS Code.

Start the server

Use the MCP controls in VS Code to start or restart the marble server.

You can also create .vscode/mcp.json manually:

{
  "servers": {
    "marble": {
      "type": "http",
      "url": "https://mcp.marblecms.com/mcp",
      "headers": {
        "Mcp-Marble-Api-Key": "${MCP_MARBLE_API_KEY}"
      }
    }
  }
}

Add the remote MCP server with:

claude mcp add --transport http marble https://mcp.marblecms.com/mcp \
  --header "Mcp-Marble-Api-Key: ${MCP_MARBLE_API_KEY}"

Set your API key in your shell before starting Claude Code:

export MCP_MARBLE_API_KEY="<your-api-key>"

Add Marble to your Codex MCP configuration:

[mcp_servers.marble]
command = "npx"
args = [
  "mcp-remote",
  "https://mcp.marblecms.com/mcp",
  "--header",
  "Mcp-Marble-Api-Key:${MCP_MARBLE_API_KEY}"
]

[mcp_servers.marble.env]
MCP_MARBLE_API_KEY = "<your-api-key>"

Some MCP clients support remote Streamable HTTP servers directly:

{
  "mcpServers": {
    "marble": {
      "type": "streamableHttp",
      "url": "https://mcp.marblecms.com/mcp",
      "headers": {
        "Mcp-Marble-Api-Key": "${MCP_MARBLE_API_KEY}"
      }
    }
  }
}

Clients that only support local stdio servers can connect through mcp-remote:

{
  "mcpServers": {
    "marble": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.marblecms.com/mcp",
        "--header",
        "Mcp-Marble-Api-Key:${MCP_MARBLE_API_KEY}"
      ],
      "env": {
        "MCP_MARBLE_API_KEY": "<your-api-key>"
      }
    }
  }
}

Available Tools

Tool badges describe how clients may present or approve tool calls:

READ-ONLY: reads data without changing your workspace
DESTRUCTIVE: may update or delete existing content

Posts

Tool	Description	Badges
`get_posts`	Get a paginated list of published posts with optional filtering.	`READ-ONLY`
`search_posts`	Search posts by title and content. Use this when an agent needs to find content before editing or linking to it.	`READ-ONLY`
`get_post`	Get a single post by ID or slug, with optional status and content format filtering.	`READ-ONLY`
`create_post`	Create a new post. Category is required. If authors are not provided, the first workspace author is used. Requires a private API key.
`update_post`	Update an existing post by ID or slug. All fields are optional, and only provided fields are updated. Requires a private API key.	`DESTRUCTIVE`
`delete_post`	Delete a post by ID or slug. Requires a private API key.	`DESTRUCTIVE`

Tool	Description	Badges
`get_categories`	Get a paginated list of categories.	`READ-ONLY`
`get_category`	Get a single category by ID or slug.	`READ-ONLY`
`create_category`	Create a new category. Requires a private API key.
`update_category`	Update an existing category by ID or slug. Requires a private API key.	`DESTRUCTIVE`
`delete_category`	Delete a category by ID or slug. Cannot delete a category that has posts assigned to it. Requires a private API key.	`DESTRUCTIVE`

Tags

Tool	Description	Badges
`get_tags`	Get a paginated list of tags.	`READ-ONLY`
`get_tag`	Get a single tag by ID or slug.	`READ-ONLY`
`create_tag`	Create a new tag. Requires a private API key.
`update_tag`	Update an existing tag by ID or slug. Requires a private API key.	`DESTRUCTIVE`
`delete_tag`	Delete a tag by ID or slug. Requires a private API key.	`DESTRUCTIVE`

Authors

Tool	Description	Badges
`get_authors`	Get a paginated list of authors who have published posts.	`READ-ONLY`
`get_author`	Get a single author by ID or slug.	`READ-ONLY`
`create_author`	Create a new author. Hobby plan workspaces are limited to 1 author. Requires a private API key.
`update_author`	Update an existing author by ID or slug. Requires a private API key.	`DESTRUCTIVE`
`delete_author`	Delete an author by ID or slug. Requires a private API key.	`DESTRUCTIVE`

Media

Tool	Description	Badges
`get_media`	Get a paginated list of media assets with optional type, search, and sort filters.	`READ-ONLY`
`get_media_asset`	Get a single media asset by ID, including its CDN URL and metadata.	`READ-ONLY`
`upload_media_from_url`	Upload media from a public URL into your Marble workspace. Requires a private API key.
`update_media`	Update media metadata such as name and alt text. Requires a private API key.	`DESTRUCTIVE`
`delete_media`	Delete a media asset and its stored file. Requires a private API key.	`DESTRUCTIVE`

Authentication

The MCP server accepts your Marble API key through one of these headers:

Mcp-Marble-Api-Key: <your-api-key>
X-Marble-Api-Key: <your-api-key>
Authorization: Bearer <your-api-key>

Keep private API keys out of client-side code and public repositories.

Troubleshooting

If your client cannot connect, verify that:

The URL ends with /mcp
The API key header is present
Your key has the permissions needed for the tool you are calling
Write operations use a private Marble API key

​Installation

Install in Cursor

Install in VS Code

​Available Tools

​Authentication

​Troubleshooting

Installation

Available Tools

Authentication

Troubleshooting