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

• Transport: stdio (stdin/stdout)
• API: CodebaseHQ REST API v3 (api3.codebasehq.com)
• Auth: HTTP Basic (account/username:api_key)
• Responses: JSON (read), XML (write bodies)
• Rate limiting: Automatic retry with backoff on 429
• Runtime dependencies: @modelcontextprotocol/sdk only

Troubleshooting

"Invalid CodebaseHQ credentials or network error"

• Double-check your CODEBASEHQ_ACCOUNT, CODEBASEHQ_USERNAME, and CODEBASEHQ_API_KEY values
• The account/username come from splitting the API Username on /
• Verify your API key in CodebaseHQ → Settings → My Profile

Server not showing in Claude Code

• Run claude mcp list to check connection status
• Make sure the path to dist/index.js is absolute
• Rebuild with pnpm run build after any source changes
• Restart Claude Code after config changes

Rate limited

• The server automatically retries after the delay
• Reduce the limit parameter in queries if hitting limits frequently

Disclaimer

This project is not affiliated with, endorsed by, or associated with aTech Media Ltd / Krystal Hosting Ltd (the makers of CodebaseHQ). It is an independent, open-source API client. You need your own CodebaseHQ account and API credentials to use it.

License

MIT