Skip to main content
Glama
MCP Octopus

MCP Octopus

by Poag

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)

Related MCP server: warmplane

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Unifies multiple MCP servers behind a single endpoint with lazy loading, auto-cleanup, Python plugins, and role-based filtering.
      2
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Runs multiple upstream MCP servers behind one local process, keeping sessions persistent and exposing a compact, policy-aware surface for tools, resources, and prompts via HTTP, CLI, and MCP-native clients.
      4
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables self-hosting many MCP endpoints from one Docker image, each registered in claude.ai as a separate connector with bearer-token access and OAuth discovery/registration. OAuth clients and tokens persist in SQLite, so restarts and updates do not disconnect those connectors.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Runs every configured MCP server once in a shared background engine and exposes them over a single HTTP endpoint, so Claude Code, Codex, Cursor, VS Code, Gemini CLI and SSH-connected remote machines all connect through one entry and pick up added, removed, or disabled servers and tools immediately. Also provides per-tool hiding, runtime supervision with logs and auto-restart, and secret storage isolated from the API.
      MIT