opengist-mcp

A Model Context Protocol (MCP) server for Opengist, the self-hosted pastebin powered by Git.

Lets MCP clients like Claude Code, Claude Desktop or Codex read, search, create, update and delete gists on your own Opengist instance: file contents and revisions, commit history, forks and likes, plus your user account.

Fourteen tools is the ceiling, not the floor: OPENGIST_ALLOW_TOOLS=essential registers a curated seven instead, and a model picks the right tool far more reliably from seven than from fourteen — see choosing which tools load.

Note: this server talks to the Opengist REST API under /api, which is available in recent Opengist releases and enabled by default (api.enabled). A running instance serves its own OpenAPI spec at GET /api/openapi.yaml — compare it against your version if a tool behaves unexpectedly.

What makes it different

Fourteen tools over one API surface, derived from the Opengist REST API and verified against a live instance: reading, searching, writing, forking and liking gists, including revisions, commit history and raw file access.

Bounded by construction. File contents are capped per file and against an overall budget, binary files are never dumped as text, and every truncation names the call that fetches the rest.

Requirements

• Node.js 22 or newer

• An Opengist instance with the REST API enabled

• An Opengist Personal Access Token (Settings → Access Tokens). Scopes:

  • gist:read — read gists, including your private and unlisted ones
  • gist:write — create, update, delete and fork gists
  • user:read — read your own account
  • user:write — only needed for set_gist_like

  A token without gist:read still works, but the API then silently returns only public gists instead of failing.

Configuration

The token is read once at startup and then removed from process.env, so it is not visible to child processes. Use https:// for anything but a loopback address — over plain http the token and every gist travel in cleartext.

If your instance's external-url is not configured, the URLs Opengist reports (and this server passes through) point at localhost. Set external-url / OG_EXTERNAL_URL on the instance so links are usable.

Choosing which tools load

OPENGIST_ALLOW_TOOLS and OPENGIST_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset of seven: list_gists, search_gists, get_gist, get_gist_file, create_gist, update_gist, delete_gist.

OPENGIST_ALLOW_TOOLS=essential
OPENGIST_ALLOW_TOOLS=list_gists,get_gist_file,create_gist
OPENGIST_DENY_TOOLS=delete_*

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under OPENGIST_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

Claude Code

claude mcp add opengist -s user \
  -e OPENGIST_URL=https://gist.example.com \
  -e OPENGIST_TOKEN=og_your_token \
  -- npx -y opengist-mcp

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "opengist": {
      "command": "npx",
      "args": ["-y", "opengist-mcp"],
      "env": {
        "OPENGIST_URL": "https://gist.example.com",
        "OPENGIST_TOKEN": "og_your_token"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.opengist]
command = "npx"
args = ["-y", "opengist-mcp"]
env = { OPENGIST_URL = "https://gist.example.com", OPENGIST_TOKEN = "og_your_token" }

Docker

docker run --rm -i \
  -e OPENGIST_URL=https://gist.example.com \
  -e OPENGIST_TOKEN=og_your_token \
  ghcr.io/ni-c/opengist-mcp:latest

-i is required — the transport is stdio. Do not add -t; a TTY corrupts the protocol stream.

From source

git clone https://github.com/ni-c/opengist-mcp.git
cd opengist-mcp
npm install
npm run build

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches opengist-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{
  "mcpServers": {
    "opengist": {
      "command": "npx",
      "args": ["-y", "opengist-mcp"],
      "env": { "OPENGIST_ALLOW_TOOLS": "essential" },
      "denyTools": ["delete_*"]
    }
  }
}

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools

Reading