# q-ring

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6 repo stars
- Author: I4cTime
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/I4cTime/q-ring
- Updated: 2026-11-14
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/q-ring

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `QRING_BACKEND`, `QRING_FILE_PASSPHRASE`, `QRING_FILE_BACKEND_PATH`, `QRING_CONFIG_DIR` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-ring
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
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-ring
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-ring
```
Replace <…> with your own values

## When to use it
- keep API keys out of plain-text `.env` files
- 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
- Store `OPENAI_API_KEY` and let the agent retrieve it through MCP.
- Compare the secret states for staging and prod.
- Promote `DATABASE_URL` from staging to prod with q-ring.

## Similar
- [oura-ring-mcp](https://affpapa.org/en/nevibecode/mcp/oura-ring-mcp.md) — MCP server · ★ 37 repo stars
- [tree-ring-memory](https://affpapa.org/en/nevibecode/hooks/tree-ring-memory.md) — hook · ★ 1596 repo stars
- [Context7](https://affpapa.org/en/nevibecode/mcp/context7.md) — MCP server · 5563 installs
- [Search Google Flights](https://affpapa.org/en/nevibecode/mcp/search-google-flights.md) — MCP server · 2595 installs
- [Math-MCP](https://affpapa.org/en/nevibecode/mcp/math-mcp.md) — MCP server · 5958 installs
- [pipeworx gateway](https://affpapa.org/en/nevibecode/mcp/pipeworx-gateway.md) — MCP server · 419019 installs
- [SparkForge](https://affpapa.org/en/nevibecode/mcp/sparkforge.md) — MCP server · 219896 installs
- [OpenWebSearch](https://affpapa.org/en/nevibecode/mcp/openwebsearch.md) — MCP server · 494 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
