Skip to content
Simply SF logoSimply SF logoSimply CLI

MCP server

simply gitlab mcp

Section titled “simply gitlab mcp”

Serve the GitLab MCP tools over stdio.

Flags

  • --allow-writes — Also register the tools that change data.
  • -e, --env-file <value> — Path to a .env file holding connection settings.
  • --list — Print the tools that would be registered, then exit without serving.

Runs a Model Context Protocol server exposing GitLab as tools, for Claude Desktop, Claude Code, Cursor, Gemini CLI, VS Code, or any other MCP client. It speaks the protocol on stdout, so it is meant to be launched by a client rather than run by hand — at a terminal it will simply appear to hang, waiting for a client that is not there.

Point a client at it with “command”: “simply”, “args”: [“gitlab”, “mcp”]. The plugin installs itself on first use, so nothing needs installing beyond the simply CLI.

Only read tools are registered unless —allow-writes is passed, and GITLAB_READ_ONLY still refuses every write even then.

Examples

Register only the read tools, taking settings from the environment

Terminal window
simply gitlab mcp

Allow writes, with settings from a file

Terminal window
simply gitlab mcp --allow-writes --env-file ~/gitlab.env

List the tools this server would register, without starting it

Terminal window
simply gitlab mcp --list

simply gitlab mcp install

Section titled “simply gitlab mcp install”

Add the GitLab MCP server to MCP clients.

Flags

  • --client <value> — Client to add the server to. Repeat for several. (one of: claude-code, claude-desktop, cursor, vscode, windsurf, gemini, codex; repeatable)
  • --scope <value> — Your own configuration, or the repository-level file in the current directory. (default: user; one of: user, project)
  • -e, --env-file <value> — Connection settings file for the server. Written as an absolute path.
  • --allow-writes — Register the tools that change data. Also makes the default name simply-gitlab-write.
  • --name <value> — Entry name. Default simply-gitlab, or simply-gitlab-write with —allow-writes.
  • --launcher <value> — How the entry starts simply. Default absolute for —scope user, simply for —scope project. (one of: absolute, simply, npx)
  • --force — Replace an existing entry of the same name that differs.
  • --dry-run — Show what would be written, and change nothing.

Global

  • --json — the raw API payload, for scripts and agents.

Writes an entry that launches “simply gitlab mcp” into each client named with —client, keeping the rest of that client’s configuration as it was. Claude Code and Codex are changed through their own CLIs; every other client’s JSON file is edited in place, with a .bak copy kept.

Credentials are never written. Give the server its connection settings with —env-file, which is written as an absolute path and must exist now. A GUI client will not pass on your shell’s environment, so without —env-file the entry starts with no settings.

Running it again is safe: an identical entry is left alone, and a different one is only replaced with —force.

Examples

Add the read-only server to Claude Code and Cursor

Terminal window
simply gitlab mcp install --client claude-code --client cursor --env-file ~/gitlab.env

Add a second, write-enabled entry (named simply-gitlab-write) to Claude Desktop

Terminal window
simply gitlab mcp install --client claude-desktop --allow-writes --env-file ~/gitlab-write.env

Commit an entry for this repository’s VS Code users

Terminal window
simply gitlab mcp install --client vscode --scope project

See what would be written, and change nothing

Terminal window
simply gitlab mcp install --client gemini --dry-run