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. Set `status` to `scheduled` with a future `publishedAt` to publish later. 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. Use it to schedule, reschedule, or unschedule a post. 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`

Scheduling Posts

Scheduling uses create_post and update_post, so there’s no separate tool. Ask your agent in plain words:

“Schedule this post for Friday at 9am.”
“Move the launch post to next Monday.”
“Publish the scheduled launch post now.”
“Unschedule the launch post.”

Times use your workspace timezone unless you name a zone, such as “9am New York time”. Your agent reads scheduled posts through a private API key. The agent repeats the go-live time back to you in UTC. Check that it matches what you asked for. The agent can’t see your workspace timezone, and older workspaces may still be on the default Europe/London. If the time looks wrong, change the timezone in Settings and reschedule the post.

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

Scheduling Posts

Authentication

Troubleshooting

​Installation

Install in Cursor

Install in VS Code

​Available Tools

​Scheduling Posts

​Authentication

​Troubleshooting

Installation

Available Tools

Scheduling Posts

Authentication

Troubleshooting