opengist-mcp

opengist-mcp is an MCP (Model Context Protocol) server for Opengist. Opengist is a self-hosted, Git-driven pastebin. This server lets MCP clients such as Claude Code, Claude Desktop, and Codex perform operations on their own Opengist instances, including reading, searching, creating, updating, and deleting gists, covering file contents and revisions, commit history, forks and likes, as well as user account information.

Main capabilities

• Provides fourteen tools covering one API surface, derived from the Opengist REST API. Features include reading, searching, writing, forking, and liking gists, and involve revisions, commit history, and raw file access.
• Can be registered via OPENGIST_ALLOW_TOOLS=essential with a curated set of seven tools: list_gists, search_gists, get_gist, get_gist_file, create_gist, update_gist, delete_gist. The description notes that a model choosing the right tool from seven tools is more reliable than choosing from fourteen.
• Results are bounded: each file content has a limit, and an overall budget is set; binary files are not output as text; every truncation indicates the call to retrieve the remaining content.
• Structured output: each tool declares an outputSchema and returns structuredContent in addition to text blocks, so clients can use the results without parsing prose.
• All tools that report gist content carry the untrusted: true and source: "opengist" fields; the three tools check_gist_like, set_gist_like, and delete_gist do not include that marker because their returns are entirely the server's own text (the given id and a boolean).

Usage

Prerequisites

• Node.js 22 or later.
• An Opengist instance with the REST API enabled (recent versions enable api.enabled by default). A running instance provides its own OpenAPI specification at GET /api/openapi.yaml .
• An Opengist personal access token (Settings → Access Tokens). Scopes include:
  • gist:read: read gists, including your own private and unlisted gists.
  • gist:write: create, update, delete, and fork gists.
  • user:read: read your own account.
  • user:write: required only by set_gist_like.
  • A token without gist:read still works, but the API silently returns only public gists instead of reporting an error.

The token is read once at startup and then removed from process.env, so it is not visible to child processes. Non-loopback addresses should use https://；在明文 http, the token and all gists are transmitted in plaintext. If the instance's external-url is not configured, the URLs reported by Opengist (and the URLs passed through by this server) will point to localhost; external-url / OG_EXTERNAL_URL should be set on the instance to make the links usable.

Tool loading selection

OPENGIST_ALLOW_TOOLS and OPENGIST_DENY_TOOLS accept comma-separated tool names, and a trailing * matches the entire family.essential is the curated preset of seven. An entry that matches no tools causes startup to abort and identifies that entry, so typos do not silently hide tools. Filtered tools are never registered, so they do not exist in tools/list and are unknown to tools/call, just like the write tools under OPENGIST_READ_ONLY .

Client configuration

For configuration examples such as claude_desktop_config.json and ~/.codex/config.toml, see the official documentation. When using the stdio transport, you must add -i, do not add -t; TTY would corrupt the protocol stream.

Clients that cannot start a local process (ChatGPT connectors, web Claude, Cursor, LibreChat) can reach opengist-mcp through mcp-hub: a single container serving multiple stdio MCP servers over Streamable HTTP, with OAuth 2.1 login (single password) and long-lived tokens for clients that do not support OAuth. Its /hub endpoint places each server behind six meta-tools. Its /config/mcp.json uses the Claude Code format. In it, allowTools and denyTools are the hub's own per-server filters, distinct from the *_ALLOW_TOOLS in env.

Security and confirmation

• Irreversible operations ask a human: delete_gist, delete_gist_files, and widening gist visibility pop up a real dialog via MCP elicitation when the client supports it, and the model cannot answer on the user's behalf. When the client cannot display a dialog, the first call is rejected and returns a random one-time token that expires after five minutes; approval for delete_gist_files is bound to the exact set of filenames, and approval for one file cannot be replayed to delete other files.ELICITATION=false will proactively adopt a fallback, but never removes the guard.
• Publishing content is also asked about: creating a public or unlisted gist, and writing files to a gist that is already public/unlisted, are disclosure events, and both are asked about before acting. Approval is bound to the exact content. A call that also makes the gist private is not a disclosure and is not asked about.
• Confirmation is checked after validation, confirmation prompts never quote gist text, and on rejection only server-side metadata is shown (visibility, file count, date).

Write guards

• update_gist cannot delete files: the Opengist API deletes a file when the entry is null or has neither content nor filename, this server never exposes the raw file map, accepts only explicit write/rename operations, and asserts before sending that no entry will be interpreted as a deletion. Files not mentioned remain unchanged.
• Typos do not silently duplicate files: writing to a nonexistent filename is rejected unless allowCreate: trueis passed, and on rejection it points out case-insensitive near matches (readme.md vs README.md).

Bounded results and input handling

gist content is untrusted input, and every response carrying file content includes a notice. Results are bounded: file content is limited per file and by an overall budget, commits and forks are omitted by default, binary files are not output as text, and every truncation is reported along with the call to fetch the remaining content. search_gists states how many were scanned and explicitly marks incomplete results.

The instance is read but not trusted: every response passes through a boundary - fields with the wrong type are missing rather than fatal, counts are limited, commit ids have the correct shape before use, display strings are truncated; every outgoing string has control characters stripped and lone surrogates repaired, and if a file body is involved, how many characters were removed is stated per file. Requests are hardened: redirects are rejected to prevent bearer tokens from being replayed to other hosts, every request has a timeout, and path parameters reject .、.. and perform URL encoding; upstream error bodies are truncated, and HTML error pages are discarded entirely.

Residual risk: OPENGIST_READ_ONLY and the approval flow are client-side protections. The real boundary is the access token's scope and the MCP host's permission prompts. A token restricted to gist:read / user:read cannot write under any circumstances.

Use cases

Suitable for users who want to manage gists on their own Opengist instance through an MCP client, including reading and searching, creating and updating, forking and liking, etc., while requiring structured output and bounded results, untrusted content marking, and human confirmation of irreversible operations.

Limitations

• Not a git client: it uses the REST API; cloning, pushing, and branching are git's responsibility, but it returns clone_url and ssh_url to hand off to git.
• Not an administration tool: it does not cover users, settings, or instance management; get_user returns an allowlisted set of fields.
• Not a search index: Opengist has no search endpoint; search_gists only uses the capabilities the API provides.
• The total number of tools is capped at fourteen; it can be reduced via environment variables.
• A token without gist:read only returns public gists, and does not report an error.
• The full guide, tool reference, and security notes are at opengist-mcp.ni-c.de (source in docs/).

Licensed under MIT © Willi Thiel.