ni-c/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.
is resolved against the colour scheme of the page showing it, so GitHub
picks the variant that matches its own theme toggle. npm strips and
when it sanitises the README and keeps the , which is why that
fallback brings its own dark card instead of relying on a media query. -->
> **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
| Variable | Required | Description |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| OPENGIST_URL | yes | Base URL of your instance, e.g. https://gist.example.com. A trailing /api is accepted and stripped. |
| OPENGIST_TOKEN | yes | Personal Access Token, starts with og_ |
| OPENGIST_READ_ONLY | no | true, 1 or yes registers only the read tools; the write tools do not exist at all in that session |
| OPENGIST_INSECURE_TLS | no | true accepts self-signed certificates, scoped to the Opengist connection (never process-wide) |
| OPENGIST_ALLOW_TOOLS | no | Comma-separated tool names, list_* prefixes, or essential for a curated preset |
| OPENGIST_DENY_TOOLS | no | Same syntax; removed from whatever OPENGIST_ALLOW_TOOLS left |
| ELICITATION | no | false replaces the approval dialog with the two-call token. **Not prefixed** |
> 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.
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.