Submit
3KniGHtcZ

codebeamer-mcp

Community 3KniGHtcZ
Updated

codebeamer-mcp

An MCP (Model Context Protocol) server for Codebeamer ALM. Allows Claude and other MCP clients to read and write projects, trackers, and items in Codebeamer using natural language.

Tools (17)

Read

Tool Description
list_projects List all projects
get_project Get project details
list_trackers List trackers in a project
get_tracker Get tracker details
list_tracker_items List items in a tracker
search_items Full-text / cbQL search
get_item Get item details
get_item_relations Get outgoing/incoming associations (depends on, blocks, …)
get_item_references Get upstream/downstream traceability references (derived from, covers, …)
get_item_comments Get item comments
get_user Get user details

Write

Tool Description
create_item Create a new item in a tracker. Supports folders, item type, and parent nesting
update_item Update an existing item (name, description, status, priority, assignee, custom fields)
add_comment Add a comment to an item
create_association Create an association between two items (e.g. depends on, blocks)
create_reference Add a downstream traceability reference between two items
create_harm Create a harm entry in an RM Harms List tracker with IMDRF code and severity (1–5)

Installation

Requirements

  • Node.js 20+
  • Access to a Codebeamer instance (URL, username, password)

Claude Code (CLI)

The fastest way — run this command in your terminal:

claude mcp add codebeamer -e CB_URL=https://your-instance.example.com/cb/api \
  -e CB_USERNAME=your_username -e CB_PASSWORD=your_password \
  -- npx -y codebeamer-mcp

Or add it manually to .mcp.json in the project root (or ~/.claude/mcp.json for global scope):

{
  "mcpServers": {
    "codebeamer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codebeamer-mcp"],
      "env": {
        "CB_URL": "https://your-instance.example.com/cb/api",
        "CB_USERNAME": "your_username",
        "CB_PASSWORD": "your_password"
      }
    }
  }
}

Claude Desktop

Edit the config file for your platform:

Platform Path
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json 
{
  "mcpServers": {
    "codebeamer": {
      "command": "npx",
      "args": ["-y", "codebeamer-mcp"],
      "env": {
        "CB_URL": "https://your-instance.example.com/cb/api",
        "CB_USERNAME": "your_username",
        "CB_PASSWORD": "your_password"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Add to .cursor/mcp.json in the project root (project scope) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "codebeamer": {
      "command": "npx",
      "args": ["-y", "codebeamer-mcp"],
      "env": {
        "CB_URL": "https://your-instance.example.com/cb/api",
        "CB_USERNAME": "your_username",
        "CB_PASSWORD": "your_password"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "codebeamer": {
      "command": "npx",
      "args": ["-y", "codebeamer-mcp"],
      "env": {
        "CB_URL": "https://your-instance.example.com/cb/api",
        "CB_USERNAME": "your_username",
        "CB_PASSWORD": "your_password"
      }
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json in the project root:

{
  "servers": {
    "codebeamer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codebeamer-mcp"],
      "env": {
        "CB_URL": "https://your-instance.example.com/cb/api",
        "CB_USERNAME": "your_username",
        "CB_PASSWORD": "your_password"
      }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "codebeamer": {
      "command": "npx",
      "args": ["-y", "codebeamer-mcp"],
      "env": {
        "CB_URL": "https://your-instance.example.com/cb/api",
        "CB_USERNAME": "your_username",
        "CB_PASSWORD": "your_password"
      }
    }
  }
}

Alternative: global install

npm install -g codebeamer-mcp

Then use "command": "codebeamer-mcp" (no args) instead of npx in any config above.

Pinning a specific version

"args": ["-y", "[email protected]"]

Updates

Method Update behavior
npx -y codebeamer-mcp Always fetches the latest version
npm install -g codebeamer-mcp Stays on installed version. Run npm update -g codebeamer-mcp to update
Pinned version (@0.2.0) Never auto-updates; change the version string manually

⚠️ Never commit .mcp.json with real credentials — it is listed in .gitignore.

From source (development)

git clone https://github.com/3KniGHtcZ/codebeamer-mcp.git
cd codebeamer-mcp
npm install
npm run build

Then use "command": "node" with "args": ["dist/index.js"] in your .mcp.json.

Development & Testing

# Run tests (no real Codebeamer instance needed)
npm test

# Start the mock API server (port 3001)
node mock-server.mjs

# Interactive testing via MCP Inspector
CB_URL=http://localhost:3001 CB_USERNAME=mock CB_PASSWORD=mock \
  npx @modelcontextprotocol/inspector node dist/index.js

Configuration

Variable Description Default
CB_URL Codebeamer API URL, e.g. https://your-instance.example.com/cb/api (the server appends /v3 automatically) (required)
CB_USERNAME Login username (required)
CB_PASSWORD Password (required)
CB_API_VERSION API version v3
CB_TIMEOUT_MS Request timeout (ms) 30000
CB_MAX_ITEMS Max items per page 100

MCP Server · Populars

MCP Server · New