跳到主要内容

连接 Claude Code

这是 Almirant 的核心集成。通过 MCP（Model Context Protocol）将 IDE 与 Almirant 连接后，AI 可读取任务、实现代码、在列之间移动工作项并创建拉取请求，所有操作都无需离开编辑器。

什么是 MCP，以及为什么要连接​

MCP（Model Context Protocol）是一种开放协议，让 AI 工具（如 Claude Code 或 Cursor）可以与外部服务双向通信。通过 MCP 连接 Almirant 后：

  • AI 可直接读取你的工作项、看板和迭代
  • AI 可在实现过程中更新任务状态
  • AI 在发现子任务时可创建新的工作项
  • AI 可访问项目上下文（技术栈、描述、目标）

要求​

开始前，请确保具备：

第 1 步：生成 API Key​

  1. 在 Almirant 中，从侧边菜单访问 设置
  2. 转到 API 密钥 区域
  3. 点击 创建 API 密钥
  4. 为它指定描述性名称（例如 "Claude Code - 工作笔记本电脑"）
  5. 复制生成的 API Key
保存 API Key

API Key 仅会在创建时显示一次。请复制并保存在安全位置。如果丢失，必须重新生成。

第 2 步：获取 Project ID​

你需要获取希望连接 AI 的项目 ID。有两种方式：

选项 A：通过 URL

在 Almirant 中打开项目，并复制浏览器 URL 中显示的 UUID：

https://almirant.ai/projects/a1b2c3d4-e5f6-7890-abcd-ef1234567890
                               └──────────── 这是你的 projectId ────────────┘

选项 B：通过 MCP 工具

如果在没有 projectId 的情况下配置连接，可以使用 list_projects 工具查看全部项目及其 IDs。

第 3 步：配置 .mcp.json​

在仓库根目录创建或编辑 .mcp.json 文件：

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=<tu-project-id>",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}

替换以下值：

占位符值
<tu-project-id>第 2 步中获取的项目 UUID
<tu-api-key>第 1 步中生成的 API Key

使用实际值的示例：

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "headers": {
        "Authorization": "Bearer alm_k7x9m2p4q8r1..."
      }
    }
  }
}
在仓库中存放 .mcp.json

可以将 .mcp.json 加入仓库，以便整个团队共享相同配置。若这样做，请将 API Key 作为环境变量添加，而不是直接包含在文件中。

第 4 步：验证连接​

在终端中打开 Claude Code，并确认连接是否正常：

  1. 在创建 .mcp.json 的项目目录中启动 Claude Code
  2. 要求 Claude 列出项目：
> 列出我的 Almirant 项目

如果连接正确，Claude 将返回项目列表。如果配置了 projectId，则会显示该特定项目的详情。

连接后可用的 MCP 工具：

工具说明
list_projects列出可用项目
list_boards列出项目看板
list_work_items使用筛选器列出工作项
create_work_item创建新工作项
update_work_item更新现有工作项
list_sprints列出项目迭代

Cursor 配置​

Cursor 的配置完全相同，区别在于配置文件的位置：

Cursor 使用相同的 .mcp.json 格式。根据所用版本的文档，将文件放在项目根目录或 Cursor 的全局配置中。

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=<tu-project-id>",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}

故障排除​

连接失败或没有响应​

  1. 检查 URL：确认 URL 是 https://api.almirant.ai/mcp（不是 https://almirant.ai/mcp）
  2. 检查 API Key：如果不确定当前 key 是否正确，请生成新的 key
  3. 检查 JSON 格式：.mcp.json 中的语法错误会阻止连接

"Unauthorized" 或 "Invalid API Key"​

  • API Key 可能已被撤销或过期
  • 在 Almirant 中前往 设置 > API 密钥 并生成新的 key
  • 更新 .mcp.json 中的值

"Project not found"​

  • 确认 URL 中的 projectId 正确
  • 确认账户具有该项目的访问权限
  • 尝试不使用 projectId，并使用 list_projects 查看可用 IDs

Claude Code 未检测到 MCP 服务器​

  • 确认 .mcp.json 文件位于运行 Claude Code 的目录根部
  • 创建或修改文件后重启 Claude Code
  • 确认 JSON 有效（没有多余逗号，且引号正确）

下一步：第一个 AI 工作流：通过 IDE 中的 AI 实现完整任务。