sitecore-gql-mcp

Ship-anywhere MCP server that turns user-defined Sitecore GraphQL queries into MCP tools. Runs on any standard Sitecore GraphQL endpoint (XP ItemService, XM Cloud, Edge). Bundles two generic tools (get_item, search) so it works out of the box; point it at a folder of your own tool definitions to extend or override.

Quick start

# get_item + search, no config, over stdio
SITECORE_API_KEY=xxx npx -y sitecore-gql-mcp \
  --endpoint https://cm.local/sitecore/api/graph/items/master

Wire it into an MCP client (Claude Code .mcp.json, VS Code .vscode/mcp.json, Copilot):

{
  "mcpServers": {
    "sitecore": {
      "command": "npx",
      "args": ["-y", "sitecore-gql-mcp", "--tools", "./my-tools"],
      "env": {
        "SITECORE_GRAPHQL_ENDPOINT": "https://cm.local/sitecore/api/graph/items/master",
        "SITECORE_API_KEY": "{APIKEY}"
      }
    }
  }
}

Define your own tools

A tool is a folder of up to three files:

my-tools/get_setting/
  index.yaml     # name, description, input (JSON Schema), variable mapping, query file
  query.gql      # the GraphQL document
  transform.js   # optional (data, args) => result — reshape the raw result

sitecore-gql-mcp init scaffolds a config file and an example get_setting tool to copy from.

• variables maps tool args onto GraphQL variables. A template of exactly {{arg}} passes the raw typed value; anything else is rendered as a string (e.g. build a path).
• transform.js default-exports (data, args) => result. Without it, an optional transform: JMESPath string is applied; without either, the raw data is returned.
• REST tools: replace query with a rest: { path, method, query } block to hit an endpoint on the same host with the same auth (for data GraphQL does not expose).

Commands

sitecore-gql-mcp                 # stdio (default)
sitecore-gql-mcp serve --port 3000   # Streamable-HTTP
sitecore-gql-mcp list                # print discovered tools
sitecore-gql-mcp validate            # load + validate tools (CI), non-zero on error
sitecore-gql-mcp init                # scaffold config + example tool
sitecore-gql-mcp --help

Configuration

CLI flag > env var > sitecore-gql-mcp.config.yaml (cwd) > default.

| Flag | Env | Default | |------|-----|---------| | --endpoint | SITECORE_GRAPHQL_ENDPOINT | (required) | | --api-key | SITECORE_API_KEY | — | | --api-key-header | SITECORE_API_KEY_HEADER | sc_apikey | | --bearer | SITECORE_BEARER | — | | --tools <dir,…> | SITECORE_MCP_TOOLS | ./tools if present | | --no-builtins | SITECORE_NO_BUILTINS | off | | --disable a,b | SITECORE_DISABLE_TOOLS | — | | --allow-mutations | SITECORE_ALLOW_MUTATIONS | off (read-only) | | --port | PORT | 3000 | | --insecure | SITECORE_INSECURE | off |

Read-only by default

Any tool whose GraphQL document contains a mutation is refused unless you pass --allow-mutations. Combined with the read-only tool annotations, the default server is safe to hand to an agent.

License

MIT