Skip to content
MCP server

q-ring

Keep API keys in your OS keychain and give coding agents only what policy allows

Runs locallyStatus and history
Pricing
Open source
Platforms
CLI, macOS, Linux
Runs
Locally
Version
0.19.2
Listing updated
3 days ago

About q-ring

q-ring is an open-source MCP server for security. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a terminal

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

Add to claude_desktop_config.json

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

Add to ~/.cursor/mcp.json

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

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Configuration

  • QRING_BACKENDSecret storage backend. Defaults to the OS keychain; set to "file" for headless hosts with no Secret Service (CI, containers).
  • QRING_FILE_PASSPHRASEPassphrase for the encrypted file backend (AES-256-GCM). Required only when QRING_BACKEND=file — without it the file backend fails closed.
  • QRING_FILE_BACKEND_PATHCustom path for the encrypted file store (default: ~/.config/q-ring/file-backend.enc).
  • QRING_CONFIG_DIRDirectory for q-ring's registries — hooks, entanglement, approvals, canary webhooks, agent memory (default: ~/.config/q-ring).

What it does

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

Pricing

Open source

Free and open source (AGPL-3.0)

Prices change. Check qring.i4c.studio before you buy.

q-ring 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 to q-ring

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools