# Portunus

> Portunus is an open-source MCP server for security. Secret broker that injects credentials at the point of use, never into the model. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, self-hosted
- **Website:** https://mdostal.github.io/portunus/
- **Repository:** https://github.com/mdostal/portunus
- **MCP Registry name:** io.github.mdostal/portunus
- **Categories:** security, developer tools
- **Listing updated:** 2026-11-15

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

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

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

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

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

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

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

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

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

## 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

- [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/portunus
