配置指南

本指南提供了关于如何将 Model Context Protocol（MCP）服务器与 Kiro 进行配置的详细信息，包括配置文件结构、服务器设置以及最佳实践。

配置文件结构

MCP 配置文件使用 JSON 格式，结构如下：

  1. {
  2.   "mcpServers": {
  3.     "server-name": {
  4.       "command": "command-to-run-server",
  5.       "args": ["arg1", "arg2"],
  6.       "env": {
  7.         "ENV_VAR1": "value1",
  8.         "ENV_VAR2": "value2"
  9.       },
  10.       "disabled": false,
  11.       "autoApprove": ["tool_name1", "tool_name2"]
  12.     }
  13.   }
  14. }

配置属性说明

属性名 类型 是否必填 描述
command String 是 用于启动 MCP 服务器的命令
args Array 是 传递给命令的参数
env Object 否 MCP 服务器进程所需的环境变量
disabled Boolean 否 是否禁用该服务器（默认值：false）
autoApprove Array 否 设置为无需确认自动批准的工具名称

配置文件的位置

你可以在两个级别配置 MCP 服务器：

  1. 工作区级别：.kiro/settings/mcp.json

    • 仅对当前工作区生效
    • 适合为特定项目配置专用 MCP 服务器

  2. 用户级别：~/.kiro/settings/mcp.json

    • 全局适用于所有工作区
    • 适合配置你经常使用的 MCP 服务器

如果两个配置文件同时存在，将合并配置项，其中工作区设置优先生效。

创建配置文件

通过 Command Palette（命令面板）

  1. 打开命令面板：

    • Mac：Cmd + Shift + P
    • Windows/Linux：Ctrl + Shift + P

  2. 搜索 “MCP”，然后选择以下选项之一：

    • Kiro: Open workspace MCP config (JSON) - 用于工作区级别配置
    • Kiro: Open user MCP config (JSON) - 用于用户级别配置

通过 Kiro 面板

  1. 打开 Kiro 面板
  2. 点击 Open MCP Config 图标

示例：

  1. {
  2.   "mcpServers": {
  3.     "web-search": {
  4.       "command": "npx",
  5.       "args": ["-y", "@modelcontextprotocol/server-bravesearch"],
  6.       "env": {
  7.         "BRAVE_API_KEY": "your-api-key"
  8.       }
  9.     }
  10.   }
  11. }

环境变量（Environment Variables）

很多 MCP 服务器需要环境变量进行身份验证或配置：

  1. {
  2.   "mcpServers": {
  3.     "server-name": {
  4.       "env": {
  5.         "API_KEY": "your-api-key",
  6.         "DEBUG": "true",
  7.         "TIMEOUT": "30000"
  8.       }
  9.     }
  10.   }
  11. }

临时禁用服务器

如果你希望暂时禁用某个 MCP 服务器，而不删除其配置，可以这样设置：

  1. {
  2.   "mcpServers": {
  3.     "server-name": {
  4.       "disabled": true
  5.     }
  6.   }
  7. }

安全最佳实践

在配置 MCP 服务器时，建议遵循以下安全建议：

  • 不要将包含敏感令牌的配置文件 提交到版本控制系统中
  • 尽量使用环境变量 来保存敏感信息
  • 在将工具加入 autoApprove 之前，仔细审查其权限
  • 项目专用的服务器应使用 工作区级别的配置
  • 定期更换 配置中使用的 API key 和 token

配置问题排查

如果你的 MCP 配置无法正常工作，可以按照以下步骤排查：

  1. 检查 JSON 语法：

    • 确保 JSON 语法无误，例如逗号、引号、括号等是否缺失

  2. 验证命令路径：

    • 确保配置中使用的命令存在于系统的 PATH 中
    • 你可以在终端中手动运行该命令进行测试

  3. 检查环境变量：

    • 确保所有必需的环境变量都已设置
    • 检查变量名是否拼写正确

  4. 重启 Kiro：

    • MCP 配置变更后需要重启 Kiro 才能生效
    • 请关闭并重新打开 Kiro 应用