Portunus
Secret broker that injects credentials at the point of use, never into the model
- 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.0Add to claude_desktop_config.json
{
"mcpServers": {
"portunus": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/mdostal/portunus:0.34.0"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"portunus": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/mdostal/portunus:0.34.0"
]
}
}
}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

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

GitHub
MCP serverOfficial MCP server connecting AI assistants to GitHub repos, issues and workflows
Not checked yet- Remote
- Open source
- 34.5K GitHub stars
- Developer tools

Serena MCP: the IDE for your agent
MCP serverMCP toolkit giving coding agents symbol-level code retrieval and editing
Runs locally- Open source
- 31.5K GitHub stars
- Developer tools

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Ouroboros
MCP serverSpec-first layer that pins requirements and verifies results of AI coding agent work
Runs locally- Open source
- 6.4K GitHub stars
- Developer tools