mcpopus

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
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. Plugins are installed from git repositories in the admin UI, no rebuild needed. Put a reverse proxy in front of port 8080; keep the admin port 8081 on your LAN. Docs at https://github.com/Poag/mcpopus.

MCP Octopus icon

MCP Octopus

One self-hosted MCP host. Many connectors. Each plugin on its own arm.

ci python arch image

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.toml and a Python module. See docs/PLUGINS.md.
claude.ai --> Cloudflare --> cloudflared --> Caddy --> :8080  /obsidian  /notes  /...
                                                      (admin UI on :8081, your network only)

Get started

  1. Deploy the image ghcr.io/poag/mcpopus with compose.yaml: docs/DEPLOY.md.
  2. Open the admin UI on port 8081, sign in, and scan the QR code to set up the authenticator.
  3. Plugins, then Fetch on the default source, then Install a plugin (for example obsidian).
  4. 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

Links

Details

Repository
ghcr.io/poag/mcpopus:latest
Last Updated2026-11-19
First Seen2026-11-19

Runtime 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

Public listenerPorttcp

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 listenerPorttcp

Admin UI. LAN only: never route it through a proxy or tunnel.

Target
8081
Default
8081
Value
8081
ConfigPathrw

Plugin settings with encrypted secrets.

Target
/config
Default
/mnt/user/appdata/mcpopus/config
Value
/mnt/user/appdata/mcpopus/config
DataPathrw

Database, audit log, plugin data and installed plugins.

Target
/data
Default
/mnt/user/appdata/mcpopus/data
Value
/mnt/user/appdata/mcpopus/data
MCPOPUS_PUBLIC_URLVariable

Public https name Claude reaches the host by (no path, no trailing slash).

Default
https://mcp.example.com
Value
https://mcp.example.com
MCPOPUS_SECRET_KEYVariable

Encrypts stored secrets. Make one with: docker run --rm ghcr.io/poag/mcpopus:latest genkey. Keep a copy; losing it loses stored plugin secrets.

MCPOPUS_ADMIN_PASSWORDVariable

Admin UI password, 14+ characters.

MCPOPUS_OAUTH_PASSWORDVariable

Connector sign-in password, different from the admin one.

MCPOPUS_ADMIN_ALLOWED_HOSTSVariable

Hostnames you browse the admin UI by, comma separated (IP addresses always work).

MCPOPUS_TRUST_PROXY_HEADERSVariable

true only if port 8080 is reachable solely through your reverse proxy.

Default
false
Value
false
TZVariable

Timezone, e.g. Europe/London.

Default
UTC
Value
UTC