Skip to content
MCP server

Portunus

Secret broker that injects credentials at the point of use, never into the model

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, macOS, self-hosted
Runs
Locally
Version
0.34.0
Listing updated
2 days ago

About Portunus

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

Agents refer to a secret by metadata, for example {{secret:stripe-key}} or an anthropic/demo/prod triple, and Portunus resolves and injects the real value only where the call runs. The value never enters the model's context, logs or tool output, and the README says a test asserts this for every boundary path, including failures. Ambiguous matches fail closed and list candidates instead of guessing.

It sits in front of a vault you already run rather than storing secrets itself. Working backends today are GCP Secret Manager, a local encrypted vault and Chrome's saved logins read-only; AWS, Vault, Infisical, Doppler, 1Password and Azure are listed as stubs. Injection targets are an environment variable, a file, subprocess arguments or a 0600 temp file.

One core is exposed three ways: an MCP server with 21 tools, a 35-command CLI and a web UI with a macOS menu-bar shell. Requests pass an approval gate with time-boxed approvals and optional per-agent scoping, and every decision lands in a hash-chained audit log. An installer wires it into Claude Code and Codex CLI.

Install

Run in a terminal

claude mcp add portunus -- docker run -i --rm ghcr.io/mdostal/portunus:0.34.0

Add to claude_desktop_config.json

{
  "mcpServers": {
    "portunus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mdostal/portunus:0.34.0"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "portunus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mdostal/portunus:0.34.0"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "portunus": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mdostal/portunus:0.34.0"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "portunus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mdostal/portunus:0.34.0"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "portunus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mdostal/portunus:0.34.0"
      ]
    }
  }
}

What it does

Boundary-only injection
Values are injected into env vars, files, argv or temp files, never returned to the agent.
Resolve by metadata
Find a secret by org, project and environment, with fail-closed ambiguity handling.
Bring your own vault
Works with GCP Secret Manager, a local encrypted vault and Chrome logins today.
Approval gate
Time-boxed approvals and opt-in per-agent access scoped by org, project, env and repo.
Tamper-evident audit log
Hash-chained record of every allowed or denied request.
Agent installer
One command wires the MCP server into Claude Code and Codex CLI.

Good for

  • Let a coding agent deploy without seeing the deploy token
  • Call an API from an agent while keeping the key out of transcripts
  • Audit which agent requested which secret
  • Put a controlled layer over GCP Secret Manager for agents

Pricing

Open source

Free and open source

Prices change. Check mdostal.github.io before you buy.

Portunus FAQ

Does it store my secrets?

No. It is a broker over a vault you already run, though a local encrypted vault is available.

Which backends work today?

GCP Secret Manager, a local Fernet-encrypted vault and Chrome's saved logins; others are stubs.

Is it free?

The site says it is free and open source.

How do I run it?

As a CLI and MCP tool, a local web UI or a macOS menu-bar app; the registry package is an OCI image.

Is Portunus free?

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

How do I add Portunus to Claude Code?

Run this command in your terminal: claude mcp add portunus -- docker run -i --rm ghcr.io/mdostal/portunus:0.34.0

What are the best alternatives to Portunus?

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

Alternatives to Portunus

  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