q-ring — Claude Code MCP server: what it does, how to install
q-ring is a Claude Code MCP server that keeps secrets in the operating system keychain and exposes them to coding agents. Environment-specific values resolve from project context.
AGPL-3.0 ★ 6 updated 2026-11-14
claude mcp add --env QRING_BACKEND=<QRING_BACKEND> --env QRING_FILE_PASSPHRASE=<QRING_FILE_PASSPHRASE> --env QRING_FILE_BACKEND_PATH=<QRING_FILE_BACKEND_PATH> --env QRING_CONFIG_DIR=<QRING_CONFIG_DIR> --transport stdio q-ring -- npx -y @i4ctime/q-ringWhat q-ring does
q-ring stores API keys and other credentials in the native vault provided by macOS, Linux, or Windows, then exposes them to an agent through MCP. It includes 46 MCP tools for environment-aware values, linked secrets, generated credentials, and short-lived secret data.
Environment selection can use --env, QRING_ENV, NODE_ENV, Git branch rules, or .q-ring.json. Claude Code starts the package @i4ctime/q-ring through npx. A Docker container has no access to the host OS keychain, so that mode is limited to MCP access and ephemeral use rather than durable local storage.
What it helps with
- keep API keys out of plain-text
.envfiles - maintain separate secret values for dev, staging, and prod
- propagate one secret across projects
- expose credentials to an agent through MCP
- create secrets that expire by time or read count
Example prompts for the agent
- Store
OPENAI_API_KEYand let the agent retrieve it through MCP. - Compare the secret states for staging and prod.
- Promote
DATABASE_URLfrom staging to prod with q-ring.
How to install q-ring
Platform CLI
claude mcp add --env QRING_BACKEND=<QRING_BACKEND> --env QRING_FILE_PASSPHRASE=<QRING_FILE_PASSPHRASE> --env QRING_FILE_BACKEND_PATH=<QRING_FILE_BACKEND_PATH> --env QRING_CONFIG_DIR=<QRING_CONFIG_DIR> --transport stdio q-ring -- npx -y @i4ctime/q-ringReplace <…> with your own values
Platform CLI
codex mcp add q-ring --env QRING_BACKEND=<QRING_BACKEND> --env QRING_FILE_PASSPHRASE=<QRING_FILE_PASSPHRASE> --env QRING_FILE_BACKEND_PATH=<QRING_FILE_BACKEND_PATH> --env QRING_CONFIG_DIR=<QRING_CONFIG_DIR> -- npx -y @i4ctime/q-ringReplace <…> with your own values
Config file
{
"mcpServers": {
"q-ring": {
"command": "npx",
"args": [
"-y",
"@i4ctime/q-ring"
],
"env": {
"QRING_BACKEND": "<QRING_BACKEND>",
"QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>",
"QRING_FILE_BACKEND_PATH": "<QRING_FILE_BACKEND_PATH>",
"QRING_CONFIG_DIR": "<QRING_CONFIG_DIR>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"q-ring": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@i4ctime/q-ring"
],
"env": {
"QRING_BACKEND": "<QRING_BACKEND>",
"QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>",
"QRING_FILE_BACKEND_PATH": "<QRING_FILE_BACKEND_PATH>",
"QRING_CONFIG_DIR": "<QRING_CONFIG_DIR>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e QRING_BACKEND=<QRING_BACKEND> -e QRING_FILE_PASSPHRASE=<QRING_FILE_PASSPHRASE> -e QRING_FILE_BACKEND_PATH=<QRING_FILE_BACKEND_PATH> -e QRING_CONFIG_DIR=<QRING_CONFIG_DIR> q-ring npx -y @i4ctime/q-ringReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about q-ring
How do I install q-ring in Claude Code?
Run claude mcp add q-ring -e QRING_FILE_PASSPHRASE=<QRING_FILE_PASSPHRASE> -- npx -y @i4ctime/q-ring.
What does q-ring do?
q-ring puts secrets in the operating system keychain and gives coding agents MCP tools for retrieving, generating, sharing, and resolving credentials by environment.
What does q-ring require to work?
The installation command uses npx. Durable local storage relies on the native keychain on macOS, Linux, or Windows; the Docker mode cannot access that keychain.