MCP Keyring Injector

MCP钥匙圈注射器

Claude Code MCP服务器的会话范围凭据管理。API密钥在启动时自动从操作系统密钥环中注入，在退出时删除-只有在Claude Code运行时，凭据才存在于配置文件中。

 

问题

Claude Code中的MCP服务器在其环境配置中需要API密钥(~/.claude.json).将API密钥存储在配置文件中存在安全风险：

• 密钥以明文形式存储在磁盘上
• 容易无意中提交到git
• 在所有项目中共享
• 在不编辑配置的情况下很难旋转

解决方案

这个插件通过以下方式解决了这个问题：

1. 将API密钥存储在 系统钥匙圈 （加密）
2. 动态注射 他们进入 ~/.claude.json 当Claude代码启动时（SessionStart钩子）
3. 自动删除 会话结束时使用它们（SessionEnd钩子）
4. 工作 交叉平台的 （Linux、macOS、Windows）

配置文件中存在密钥 仅当Claude Code正在运行时 -真正的会话范围安全！

特性

• 安全：密钥以加密方式存储在系统密钥环中
• 跨平台：适用于Linux（GNOME钥匙圈）、macOS（钥匙链）、Windows（凭据管理器）
• 自动：在每次Claude Code会话开始时运行
• 灵活的：从一个文件配置多个MCP服务
• 最小开销：对会话启动的性能影响可忽略不计

安装

1.安装插件

# Via Claude Code plugin system
/plugin marketplace add astrogilda/claude-plugins
/plugin install mcp-keyring-injector

# Or manually
git clone https://github.com/astrogilda/mcp-keyring-injector.git ~/Documents/mcp-keyring-injector

2.安装Python依赖项

uv pip install keyring

3.存储您的第一个API密钥

选择您的平台：

Linux（GNOME密钥环）：

python3 -c "import keyring; keyring.set_password('github', 'api-key', 'YOUR_API_KEY')"

macOS（钥匙链）：

security add-generic-password -s github -a api-key -w YOUR_API_KEY

Windows（PowerShell）：

cmdkey /generic:github /user:api-key /pass:YOUR_API_KEY

4.配置MCP凭据

创建 ~/.claude/config/mcp-credentials.json:

{
  "github": {
    "env_var": "GITHUB_TOKEN",
    "service": "github",
    "account": "api-key",
    "label": "GitHub API Token",
    "mcp_server": "github-mcp"
  }
}

看 examples/mcp-credentials.json 更多示例。

5.验证其是否正常工作

重新启动克劳德代码。您应该看到：

MCP credentials - Injected: GitHub API Token

检查你的GitHub MCP工具现在可用！

从v1.0.0升级

如果您从v1.0.0升级，以下是v1.1.0中的更改：

最新动态

• 会话结束清理钩：当Claude Code退出时，凭据现在会自动删除
• 会话范围的安全性：密钥仅存在于 ~/.claude.json 克劳德跑步的时候
• 增强的状态消息：更好地反馈清理行动

迁移步骤

1. 更新插件 （如果使用插件市场，则自动）：

   /plugin update mcp-keyring-injector

1. 一次性清理 -从配置中删除旧凭据（它们不会自动清理）：

   # Backup first
   cp ~/.claude.json ~/.claude.json.backup

   # Remove credentials manually from ~/.claude.json env sections
   # Or let them be removed on next session start

1. 无需更改配置 -你的 mcp-credentials.json 格式保持不变

重大变更

• 没有！ 这是一个完全向后兼容的安全增强功能

升级后会发生什么

• 下一环节：开始时注入凭据（与之前一样）
• 新行为：会话结束时自动删除凭据
• 钥匙在系统钥匙圈中始终保持安全

配置

配置文件格式

~/.claude/config/mcp-credentials.json:

{
  "service-name": {
    "env_var": "ENVIRONMENT_VARIABLE_NAME",
    "service": "keyring-service-name",
    "account": "keyring-account-name",
    "label": "Human Readable Label",
    "mcp_server": "mcp-server-name-in-claude.json"
  }
}

领域：

• env_varMCP服务器期望的环境变量（例如。， GITHUB_TOKEN)
• service：钥匙扣服务名称（您如何存储钥匙）
• account：密钥环帐户/用户名（您如何存储密钥）
• label：在状态消息中显示名称
• mcp_server：MCP服务器名称来自 ~/.claude.json （如果省略，则默认为服务名称）

添加多种服务

{
  "github": {
    "env_var": "GITHUB_TOKEN",
    "service": "github",
    "account": "api-key",
    "label": "GitHub API Token",
    "mcp_server": "github-mcp"
  },
  "openai": {
    "env_var": "OPENAI_API_KEY",
    "service": "openai",
    "account": "api-key",
    "label": "OpenAI API Key",
    "mcp_server": "openai-mcp"
  }
}

运作原理

Claude Code Session Start
         |
SessionStart hook triggered
         |
Read ~/.claude/config/mcp-credentials.json
         |
For each service:
  |-- Retrieve API key from system keyring
  |-- Inject into ~/.claude.json MCP server env
  +-- Report success/failure
         |
Claude Code continues startup
         |
MCP servers start with injected credentials
         |
[... Claude Code session runs ...]
         |
Claude Code Session End
         |
SessionEnd hook triggered
         |
Read ~/.claude/config/mcp-credentials.json
         |
For each service:
  |-- Remove API key from ~/.claude.json MCP server env
  +-- Report cleanup status
         |
Keys removed from config
         |
Keys remain only in system keyring

安全注意事项

这能防止什么

• \[是\]明文配置文件中的API密钥
• \[是\]意外的git秘密提交
• \[是\]未经授权的文件访问（密钥环需要用户身份验证）
• \[是\] 会话范围安全（v1.1.0+）：Claude Code退出时自动删除密钥

这并不能防止什么

• \[否\]具有您的用户权限的恶意代码（可以访问密钥环）
• \[否\]物理访问未锁定的机器
• \[否\]Claude Code运行时内存转储

最佳实践

1. 每台机器使用唯一的API密钥
2. 定期旋转按键
3. 使用最少特权API密钥（可能时为只读）
4. 不要分享 ~/.claude/config/mcp-credentials.json （这不是秘密，但列出了你的服务）

故障排除

“MCP凭据-失败：X（不在密钥环中）”

密钥未存储在您的系统密钥环中。

解决方案：

python3 -c "import keyring; keyring.set_password('service', 'account', 'YOUR_KEY')"

“MCP凭据-失败：X（找不到MCP服务器'Y'）”

MCP服务器名称与中的名称不匹配 ~/.claude.json.

解决方案： 检查您的MCP服务器名称：

jq '.mcpServers | keys' ~/.claude.json

更新 mcp_server 配置中的字段要匹配。

“错误：未安装密钥环库”

缺少Python密钥环库。

解决方案：

uv pip install keyring

吊钩运行，但工具仍不可用

检查MCP服务器日志：

ls ~/.cache/claude-cli-nodejs/*/mcp-logs-*/
cat ~/.cache/claude-cli-nodejs/*/mcp-logs-github-mcp/*.txt

查找有关缺少API密钥的错误。

发展

项目结构

mcp-keyring-injector/
.claude-plugin/
  +-- plugin.json             # Plugin metadata
hooks/
  +-- hooks.json              # Hook configuration
  +-- inject-credentials.py  # SessionStart hook
  +-- remove-credentials.py  # SessionEnd hook (v1.1.0+)
examples/
  +-- mcp-credentials.json    # Example config
docs/
  +-- SECURITY.md             # Security considerations
CHANGELOG.md                # Version history
README.md
LICENSE

本地测试

# Test the hook directly
echo '{}' | ~/Documents/claude-mcp-credentials/hooks/inject-credentials.py

# Check if keys were injected
jq '.mcpServers."github-mcp".env' ~/.claude.json

贡献

欢迎投稿！拜托：

1. 分叉回购
2. 创建要素分支
3. 添加新功能的测试
4. 确保代码通过黑色+褶皱
5. 提交带有清晰描述的PR

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

鸣谢

由...创建 @阿斯特罗吉尔达

使用优秀 钥匙环 杰森·R·库姆斯的图书馆。

链接

• Claude代码文档
• MCP协议
• Python密钥库