Marble MCP Server

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 open-source add-mcp CLI. It detects supported agents and writes each client’s native MCP configuration.

add-mcp is maintained separately from Marble and writes configuration files on your machine. By default it writes project-level configuration; -g writes user-level configuration. Review the agents and scope it selects before confirming.

npx add-mcp https://mcp.marblecms.com/mcp \
  --header 'Authorization: ${MCP_MARBLE_API_KEY}' \
  -g

Leave the placeholder in single quotes so your shell does not expand it before add-mcp runs. Because the command is interactive, the CLI prompts for the key and the selected agents. Use -a <agent> to target specific clients, or omit -g to install at project scope.

Cursor
VS Code
Claude Code
Codex
Manual

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:

Authorization: ${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": {
        "Authorization": "${MCP_MARBLE_API_KEY}"
      }
    }
  }
}

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": {
        "Authorization": "${MCP_MARBLE_API_KEY}"
      }
    }
  }
}

Add the remote MCP server with:

claude mcp add --transport http marble https://mcp.marblecms.com/mcp \
  --header 'Authorization: ${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",
  "Authorization: ${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": {
        "Authorization": "${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",
        "Authorization: ${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`

Fields

Tool	Description	Badges
`get_fields`	Get all custom field definitions, including select and multiselect options.	`READ-ONLY`
`get_field`	Get a single custom field by ID or key.	`READ-ONLY`
`create_field`	Create a custom field definition. Requires a private API key.
`update_field`	Update a custom field by ID or key. Type and options cannot be changed after values have been saved. Requires a private API key.	`DESTRUCTIVE`
`delete_field`	Delete a custom field and its saved values. Requires a private API key.	`DESTRUCTIVE`

Authentication

The MCP server accepts your Marble API key through the standard API header:

Authorization: <your-api-key>

The Bearer prefix is also accepted, but is not required by Marble. For clients that need a custom header, these compatibility aliases are also accepted:

Mcp-Marble-Api-Key: <your-api-key>
X-Marble-Api-Key: <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

Getting Started

Concepts

Features

Integrations

Tools

Recipes

Installation

Install in Cursor

Install in VS Code

Available Tools

Authentication

Troubleshooting

​Installation

Install in Cursor

Install in VS Code

​Available Tools

​Authentication

​Troubleshooting

Installation

Available Tools

Authentication

Troubleshooting