mcpopus
Docker app from Uirel's Repository
MCP Octopus: one self-hosted MCP host serving several MCP endpoints (one per plugin) with built-in OAuth, for use as custom connectors in Claude.
Overview
Readme
View on GitHubMCP Octopus
One self-hosted MCP host. Many connectors. Each plugin on its own arm.
MCP Octopus runs a single process that serves several MCP endpoints, one per plugin
(https://mcp.example.com/<plugin>). Add each as its own custom connector in claude.ai. Plugins are installed from git
repositories in the admin UI and loaded, unloaded and reloaded at run time, so adding one never needs an image rebuild.
Why
- Your data stays yours. Runs on your own hardware (it was built for a Raspberry Pi 4), behind your own reverse proxy.
- One sign-in, scoped tokens. A built-in OAuth 2.1 server for one owner (password plus authenticator code, PKCE S256, dynamic client registration, refresh rotation). A token is bound to one plugin and rejected on every other.
- Safe by default. Read-only until you say otherwise, tick-box tool policy, rate limits, output caps, audit log, secrets encrypted at rest.
- Easy to run. A Dockhand-style admin UI on a separate internal port: a Home page of plugin cards, plugin settings, sources, access, audit, and authenticator set-up with a QR code.
- Extensible. A plugin is a folder with a
plugin.tomland a Python module. See docs/PLUGINS.md.
claude.ai --> Cloudflare --> cloudflared --> Caddy --> :8080 /obsidian /notes /...
(admin UI on :8081, your network only)
Get started
- Deploy the image
ghcr.io/poag/mcpopuswithcompose.yaml: docs/DEPLOY.md. - Open the admin UI on port 8081, sign in, and scan the QR code to set up the authenticator.
- Plugins, then Fetch on the default source, then Install a plugin (for example
obsidian). - Add
https://<your host>/<plugin>as a custom connector in claude.ai: docs/SPIKE.md.
A full worked example, from the first sign-in to Claude reading a note, is in the plugins repository: Set up Obsidian with Claude.
Plugins
Ready-made plugins live in Poag/mcpopus-plugins, the default source in the admin UI. Plugins run inside the host process and are trusted code: read what you install (docs/SECURITY.md).
Try it locally
python -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest
export MCPOPUS_PUBLIC_URL=http://127.0.0.1:8080 MCPOPUS_SECRET_KEY="$(.venv/bin/mcpopus genkey)" \
MCPOPUS_DATA_DIR=./data MCPOPUS_CONFIG_DIR=./config MCPOPUS_PLUGINS_DIR=./plugins
.venv/bin/mcpopus init --realm oauth
.venv/bin/mcpopus run
Documentation
| Guide | What is in it |
|---|---|
| DEPLOY.md | Dockhand, Caddy, cloudflared, keeping the admin listener internal, settings reference |
| SPIKE.md | Connecting to claude.ai and what to report if it fails |
| PLUGINS.md | Writing a plugin, with a worked example (plugins/notes) |
| SECURITY.md | Trust model, measures, accepted risks |
| BUILD_LOG.md | What was verified, decisions, lessons |
Licence
MIT. Plugins in mcpopus-plugins are MIT too; third-party notices are listed there.
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/poag/mcpopus:latestRuntime arguments
- Web UI
http://[IP]:[PORT:8081]/- Network
bridge- Shell
bash- Privileged
- false
- Extra Params
--user 99:100 --cap-drop=ALL --security-opt=no-new-privileges:true
Template configuration
MCP and OAuth endpoints. Put your reverse proxy / tunnel in front of this; do not expose it directly.
- Target
- 8080
- Default
- 8080
- Value
- 8080
Admin UI. LAN only: never route it through a proxy or tunnel.
- Target
- 8081
- Default
- 8081
- Value
- 8081
Plugin settings with encrypted secrets.
- Target
- /config
- Default
- /mnt/user/appdata/mcpopus/config
- Value
- /mnt/user/appdata/mcpopus/config
Database, audit log, plugin data and installed plugins.
- Target
- /data
- Default
- /mnt/user/appdata/mcpopus/data
- Value
- /mnt/user/appdata/mcpopus/data
Public https name Claude reaches the host by (no path, no trailing slash).
- Default
- https://mcp.example.com
- Value
- https://mcp.example.com
Encrypts stored secrets. Make one with: docker run --rm ghcr.io/poag/mcpopus:latest genkey. Keep a copy; losing it loses stored plugin secrets.
Admin UI password, 14+ characters.
Connector sign-in password, different from the admin one.
Hostnames you browse the admin UI by, comma separated (IP addresses always work).
true only if port 8080 is reachable solely through your reverse proxy.
- Default
- false
- Value
- false
Timezone, e.g. Europe/London.
- Default
- UTC
- Value
- UTC