> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marblecms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Marble MCP Server

> Connect Claude, Cursor, and other Model Context Protocol clients to your Marble workspace to read, create, and manage content with AI agents.

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

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

## Installation

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<Tabs>
  <Tab title="Cursor">
    <Card title="Install in Cursor" icon="https://mintcdn.com/marblecms/HeUo3qaHbsCXRx9S/images/cursor.svg?fit=max&auto=format&n=HeUo3qaHbsCXRx9S&q=85&s=769b72a204a886e8872602f37e6e5f6a" href="cursor://anysphere.cursor-deeplink/mcp/install?name=marble&config=eyJ0eXBlIjoic3RyZWFtYWJsZUh0dHAiLCJ1cmwiOiJodHRwczovL21jcC5tYXJibGVjbXMuY29tL21jcCIsImhlYWRlcnMiOnsiTWNwLU1hcmJsZS1BcGktS2V5IjoiJHtNQ1BfTUFSQkxFX0FQSV9LRVl9In19" arrow={false} width="467" height="533" data-path="images/cursor.svg">
      Open Cursor with the Marble MCP server pre-filled.
    </Card>

    <Steps>
      <Step title="Open the installer">
        Click **Install in Cursor** and allow your browser to open Cursor.
      </Step>

      <Step title="Add your API key">
        Cursor installs the server with this header:

        ```txt theme={"theme":{"light":"github-light","dark":"github-dark"}}
        Mcp-Marble-Api-Key: ${MCP_MARBLE_API_KEY}
        ```

        Set `MCP_MARBLE_API_KEY` in your environment before starting Cursor.
      </Step>

      <Step title="Verify the connection">
        Open Cursor's MCP settings and confirm that the `marble` server is
        enabled. The server URL should end with `/mcp`.
      </Step>
    </Steps>

    You can also add the server manually in Cursor:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcpServers": {
        "marble": {
          "type": "streamableHttp",
          "url": "https://mcp.marblecms.com/mcp",
          "headers": {
            "Mcp-Marble-Api-Key": "${MCP_MARBLE_API_KEY}"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    <Card title="Install in VS Code" icon="https://mintcdn.com/marblecms/HeUo3qaHbsCXRx9S/images/vscode.svg?fit=max&auto=format&n=HeUo3qaHbsCXRx9S&q=85&s=a339d3a61b277b1273c92111db2fc538" href="vscode:mcp/install?%7B%22name%22%3A%22marble%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.marblecms.com%2Fmcp%22%2C%22headers%22%3A%7B%22Mcp-Marble-Api-Key%22%3A%22%24%7BMCP_MARBLE_API_KEY%7D%22%7D%7D" arrow={false} width="100" height="100" data-path="images/vscode.svg">
      Open VS Code with the Marble MCP server pre-filled.
    </Card>

    <Steps>
      <Step title="Open the installer">
        Click **Install in VS Code** and allow your browser to open VS Code.
      </Step>

      <Step title="Add your API key">
        Set `MCP_MARBLE_API_KEY` in your environment before starting VS Code.
      </Step>

      <Step title="Start the server">
        Use the MCP controls in VS Code to start or restart the `marble` server.
      </Step>
    </Steps>

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

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "servers": {
        "marble": {
          "type": "http",
          "url": "https://mcp.marblecms.com/mcp",
          "headers": {
            "Mcp-Marble-Api-Key": "${MCP_MARBLE_API_KEY}"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    Add the remote MCP server with:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    export MCP_MARBLE_API_KEY="<your-api-key>"
    ```
  </Tab>

  <Tab title="Codex">
    Add Marble to your Codex MCP configuration:

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    [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>"
    ```
  </Tab>

  <Tab title="Manual">
    Some MCP clients support remote Streamable HTTP servers directly:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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`:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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>"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 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

<AccordionGroup>
  <Accordion title="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` |
  </Accordion>

  <Accordion title="Categories">
    | 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` |
  </Accordion>

  <Accordion title="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` |
  </Accordion>

  <Accordion title="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` |
  </Accordion>

  <Accordion title="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` |
  </Accordion>

  <Accordion title="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` |
  </Accordion>
</AccordionGroup>

## Authentication

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

```txt theme={"theme":{"light":"github-light","dark":"github-dark"}}
Mcp-Marble-Api-Key: <your-api-key>
X-Marble-Api-Key: <your-api-key>
Authorization: Bearer <your-api-key>
```

<Warning>
  Keep private API keys out of client-side code and public repositories.
</Warning>

## 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