# q-ring

> q-ring is an open-source MCP server for security. Keep API keys in your OS keychain and give coding agents only what policy allows. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Linux, Windows, self-hosted
- **Website:** https://qring.i4c.studio
- **Repository:** https://github.com/i4ctime/q-ring
- **MCP Registry name:** io.github.I4cTime/q-ring
- **Categories:** security, developer tools
- **Listing updated:** 2026-11-14

## About

Secrets are stored in macOS Keychain, Linux Secret Service or Windows Credential Vault, and agents such as Cursor, Claude Code and Kiro ask through MCP tools instead of reading a .env file. Each key has a policy (allow, deny or approve), pending asks wait for your decision, and every ask lands in a hash-chained audit log that a verify command checks. A canary mode plants a fake key so any read raises an alarm.

The README names four unusual mechanics: superposition (one name with separate dev, staging and prod values chosen by flag, environment variable or git branch), entanglement (linked keys that rotate together), tunneling (in-memory secrets that expire by time or read count) and teleportation (AES-256-GCM encrypted bundles to share). The package ships 46 MCP tools and 68 CLI commands, and a file backend with a passphrase serves headless hosts like CI.

It is local only, licensed AGPL-3.0, and installed from npm or Homebrew. A Docker image exists but has no OS keychain inside it.

## Features

- **OS keychain storage:** Keys live in the native vault rather than plain-text files.
- **Per-key policy:** Decide per key whether an agent is allowed, denied or must wait for approval.
- **Tamper-evident audit:** Each event carries the hash of the previous one and can be verified.
- **Canary keys:** A planted fake key flags any read as an alarm.
- **Environment-aware values:** One key name can hold different values for each environment.
- **Expiring secrets:** Ephemeral secrets self-destruct after a time or read count.

## Good for

- Let Claude Code use an API key without pasting it into chat
- Review which agent asked for which secret
- Keep dev and prod values under one key name
- Inject secrets into a command with one run call

## Install

### Claude Code (Terminal)

```sh
claude mcp add q-ring --env QRING_FILE_PASSPHRASE='<QRING_FILE_PASSPHRASE>' -- npx -y @i4ctime/q-ring
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "q-ring": {
      "command": "npx",
      "args": [
        "-y",
        "@i4ctime/q-ring"
      ],
      "env": {
        "QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "q-ring": {
      "command": "npx",
      "args": [
        "-y",
        "@i4ctime/q-ring"
      ],
      "env": {
        "QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "q-ring": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@i4ctime/q-ring"
      ],
      "env": {
        "QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "q-ring": {
      "command": "npx",
      "args": [
        "-y",
        "@i4ctime/q-ring"
      ],
      "env": {
        "QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "q-ring": {
      "command": "npx",
      "args": [
        "-y",
        "@i4ctime/q-ring"
      ],
      "env": {
        "QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>"
      }
    }
  }
}
```

## FAQ

### Does anything leave my machine?

The site says it is local only and nothing leaves your machine.

### What does it cost?

It is free and open source under AGPL-3.0.

### Does it work in CI or containers?

Set QRING_BACKEND=file with a passphrase for hosts without a keychain; the Docker image has no OS keychain.

### Which agents are supported?

Cursor, Claude Code and Kiro are named.

### Is q-ring free?

Yes. q-ring is open source, so you can use and self-host it for free.

### How do I add q-ring to Claude Code?

Run this command in your terminal: claude mcp add q-ring --env QRING_FILE_PASSPHRASE='<QRING_FILE_PASSPHRASE>' -- npx -y @i4ctime/q-ring

### What are the best alternatives to q-ring?

The closest alternatives to q-ring are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/q-ring
