CodebaseHQ MCP Server

CodebaseHQ MCP服务器

MCP（模型上下文协议）服务器，提供 克劳德代码 访问 CodebaseHQ --项目管理和票务平台。直接从Claude Code或任何兼容MCP的客户端读取、搜索、创建和更新票证。

特性

• 列出项目 --浏览CodebaseHQ帐户中的所有项目
• 搜索门票 --带分页的完整查询语法（状态、受让人、优先级、类型等）
• 查看门票详情 --获取包含状态/优先级ID的完整工单信息以进行更新
• 阅读评论 --包含作者姓名和文件附件的完整对话线程
• 活动动态 --查看最近的项目活动（谁创建/更新了什么）
• 列出团队成员 --发现要分配的用户ID
• 创建工单 --创建具有类型、优先级和受让人的新票证
• 更新门票 --添加注释、更改状态/优先级/受让人、重命名票证

先决条件

• 18+
• （或npm/yarn）
• 克劳德代码 或另一个MCP兼容客户端
• A. CodebaseHQ 具有API访问权限的帐户

设置

1.获取您的API证书

首选 CodebaseHQ→ 设置→ 我的资料 并注意：

• API用户名 --格式： account/username （例如。 mycompany/john)
• API密钥 --40个字符串

2.设置环境变量

添加到shell配置中（例如。 ~/.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.克隆和构建

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

4.用克劳德代码注册

挑选 一 下面的方法。

选项A:CLI命令（全局）

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

服务器从shell继承环境变量，因此 CODEBASEHQ_* 您在步骤2中设置的变量将被自动拾取。

选项B：全局配置文件

添加 ~/.claude.json:

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

选项C：项目范围配置

创建一个 .mcp.json 在项目根目录中（有助于与团队共享）：

{
  "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}"
      }
    }
  }
}

这 ${VAR} 语法引用shell环境变量——文件中没有秘密。

5.验证

重新启动Claude Code，然后问：

“列出我的CodebaseHQ项目”

如果服务器连接，您将看到您的项目。如果没有，请检查 故障排除.

工具

搜索查询语法

这 search_tickets 该工具支持CodebaseHQ的查询语法：

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

用法示例

问克劳德这样的问题：

• “给我看所有未结的票”
• “分配给我的票是什么？”
• “给我看23号票及其评论”
• “这个项目最近发生了什么？”
• “为登录页面问题创建错误单”
• “将票#5标记为已关闭，并添加评论”
• “谁在队里？把10号票给马里奥”

建筑

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

• 运输： stdio（标准输入/标准输出）
• API CodebaseHQ REST API v3(api3.codebasehq.com)
• 认证： HTTP基本(account/username:api_key)
• 响应： JSON（读）、XML（写体）
• 速率限制： 429上自动重试并回退
• 运行时依赖关系： @modelcontextprotocol/sdk 仅

故障排除

“CodebaseHQ凭据无效或网络错误”

• 仔细检查你的 CODEBASEHQ_ACCOUNT, CODEBASEHQ_USERNAME，以及 CODEBASEHQ_API_KEY 价值观
• 帐户/用户名来自于在上拆分API用户名 /
• 在CodebaseHQ中验证您的API密钥→ 设置→ 我的资料

克劳德代码中未显示服务器

• 跑 claude mcp list 检查连接状态
• 确保路径 dist/index.js 是绝对的
• 重建与 pnpm run build 任何源更改后
• 配置更改后重新启动Claude代码

速率限制

• 服务器在延迟后自动重试
• 减少 limit 如果频繁达到限制，则查询中的参数

免责声明

这个项目是 不隶属于、不受认可或与之相关 aTech媒体有限公司/Krystal主机有限公司（CodebaseHQ的制造商）。它是一个独立的开源API客户端。您需要自己的CodebaseHQ帐户和API凭据才能使用它。

许可证

麻省理工学院