CodebaseHQ MCP Server

CodebaseHQ MCP Server

An MCP (Model Context Protocol) server that gives Claude Code access to CodebaseHQ — a project management and ticketing platform. Read, search, create, and update tickets directly from Claude Code or any MCP-compatible client.

Features

• List projects — browse all projects in your CodebaseHQ account
• Search tickets — full query syntax (status, assignee, priority, type, etc.) with pagination
• View ticket details — get complete ticket info with status/priority IDs for updates
• Read comments — full conversation thread with author names and file attachments
• Activity feed — see recent project activity (who created/updated what)
• List team members — discover user IDs for assignment
• Create tickets — create new tickets with type, priority, and assignee
• Update tickets — add comments, change status/priority/assignee, rename tickets

Prerequisites

• Node.js 18+
• pnpm (or npm/yarn)
• Claude Code or another MCP-compatible client
• A CodebaseHQ account with API access

Setup

1. Get your API credentials

Go to CodebaseHQ → Settings → My Profile and note:

• API Username — format: account/username (e.g. mycompany/john)
• API Key — 40-character string

2. Set environment variables

Add to your shell config (e.g. ~/.zshrc, ~/.bashrc):

export CODEBASEHQ_ACCOUNT="your-account"       # the part before /
export CODEBASEHQ_USERNAME="your-username"      # the part after /
export CODEBASEHQ_API_KEY="your-api-key"
export CODEBASEHQ_DEFAULT_PROJECT="my-project"  # optional — skip the project param in every tool call

3. Clone and build

git clone https://github.com/bdteo/CodebaseHQ.git
cd CodebaseHQ
pnpm install
pnpm run build

4. Register with Claude Code

Pick one of the methods below.

Option A: CLI command (global)

claude mcp add codebasehq -- node /absolute/path/to/CodebaseHQ/dist/index.js

The server inherits environment variables from your shell, so the CODEBASEHQ_* vars you set in step 2 are picked up automatically.

Option B: Global config file

Add to ~/.claude.json:

{
  "mcpServers": {
    "codebasehq": {
      "command": "node",
      "args": ["/absolute/path/to/CodebaseHQ/dist/index.js"]
    }
  }
}

Option C: Project-scoped config

Create a .mcp.json in your project root (useful for sharing with a team):

{
  "mcpServers": {
    "codebasehq": {
      "command": "node",
      "args": ["/absolute/path/to/CodebaseHQ/dist/index.js"],
      "env": {
        "CODEBASEHQ_ACCOUNT": "${CODEBASEHQ_ACCOUNT}",
        "CODEBASEHQ_USERNAME": "${CODEBASEHQ_USERNAME}",
        "CODEBASEHQ_API_KEY": "${CODEBASEHQ_API_KEY}",
        "CODEBASEHQ_DEFAULT_PROJECT": "${CODEBASEHQ_DEFAULT_PROJECT}"
      }
    }
  }
}

The ${VAR} syntax references your shell environment variables — no secrets in the file.

5. Verify

Restart Claude Code, then ask:

"List my CodebaseHQ projects"

If the server connects, you'll see your projects. If not, check Troubleshooting.

Tools

Search Query Syntax

The search_tickets tool supports CodebaseHQ's query syntax:

status:open                    # by status
assignee:me                    # your tickets
priority:high                  # by priority
type:bug                       # Bug, Feature, or Task
category:General               # by category
sort:updated order:desc        # sorting
not-status:closed              # negation
assignee:me status:open        # combine filters

Usage Examples

Ask Claude things like:

• "Show me all open tickets"
• "What tickets are assigned to me?"
• "Show me ticket #23 and its comments"
• "What happened recently on the project?"
• "Create a bug ticket for the login page issue"
• "Mark ticket #5 as closed with a comment"
• "Who's on the team? Assign ticket #10 to Mario"

Architecture

src/
├── index.ts            # MCP server, tool definitions, request handlers
├── codebasehq-api.ts   # HTTP client (JSON responses, XML write bodies, rate limiting)
└── types.ts            # TypeScript types for API responses