cockpit-mcp

A small, read-only MCP server for Cockpit CMS. It lets an AI agent understand the content behind a page — the models, fields, and types — by asking tools, instead of fetching the whole REST API or reading docs.

Generic and reusable: point it at any Cockpit v2 instance (Core or Pro) via env vars. Write it once, reuse in every project — the code is generic; only COCKPIT_URL + COCKPIT_TOKEN change per project.

Run with npx (no install)

It runs straight from GitHub — no clone, no registry:

npx -y github:Avanxo-Technology/cockpit-mcp          # latest main
npx -y github:Avanxo-Technology/cockpit-mcp#v0.1.0   # pinned to a tag

Tools

Tool	What it does
`list_models`	List all content models (collections & singletons) with a one-line summary. Start here.
`describe_model`	Field schema for one model — names, types, required, choices, linked models, nested fields. The "understand this quickly" tool.
`list_items`	List items for a model (Mongo-style `filter`, `sort`, `fields`, `limit`).
`get_item`	Fetch one item by `_id`.
`search`	Case-insensitive substring match on a text field.

All tools are GET-only; the server never mutates content.

Setup

cd cockpit-mcp
npm install
cp .env.example .env   # then fill in COCKPIT_URL and COCKPIT_TOKEN

Create the token in Cockpit admin: Settings → API → add token (a read scope is enough).

Register with opencode / Claude (stdio)

Example MCP client config:

{
  "mcpServers": {
    "cockpit": {
      "command": "npx",
      "args": ["-y", "github:Avanxo-Technology/cockpit-mcp"],
      "env": {
        "COCKPIT_URL": "http://localhost:8080",
        "COCKPIT_TOKEN": "your-token-here"
      }
    }
  }
}

Each project registers the same package and supplies its own COCKPIT_URL / COCKPIT_TOKEN — one package, reused everywhere. (For local dev against a checkout, swap command to node with the path to src/index.js.)

The server logs a connection/health line to stderr on startup (never to stdout, which carries the JSON-RPC stream).

Compatibility

Targets Cockpit v2 (Core & Pro) REST API: GET /api/content/models, /api/content/items/{model}, /api/content/item/{model}/{id}, auth via the api-key header. On startup it probes list_models; if the URL/token is wrong it warns (auth failures surface as a clear message) and tools return errors until fixed — the server itself still starts.