Enables browsing and editing of Markdown documents through RefMD's API, with tools for listing, searching, creating, reading, and updating document content and metadata.
RefMD MCP Server
A Model Context Protocol server that exposes RefMD documents over a hosted SSE endpoint, so chatbots can browse and edit Markdown through RefMD's API.
Features
Streamable HTTP/SSE transport compatible with hosted MCP clients (e.g. Claude, Cursor)
Resource template
refmd://document/{id}to read document Markdown and metadataTools for listing, searching, creating, and updating documents via the RefMD API
Prerequisites
Node.js 18+
Access to an existing RefMD instance
Either a personal access token (JWT) or credentials that can log in via
/api/auth/login
Configuration
The server now authenticates users via OAuth 2.1 with PKCE. Configure it with the following variables:
Variable | Description |
| Required. Base URL of your RefMD API (e.g.
). |
| Comma-separated list of allowed
values. Leave empty to allow any. |
| Comma-separated list of allowed redirect URIs. Defaults to allowing HTTPS URLs and
. Include ChatGPT’s callback URL (
). |
| Optional public issuer URL (defaults to the current request origin). |
| Optional access-token lifetime (default
). |
| Optional refresh-token lifetime (default
, i.e. 30 days). |
| Optional. Set to
,
, or
to persist OAuth tokens. Defaults to in-memory storage. |
| Optional connection string for the configured driver (e.g.
). For SQLite you may omit this and use
. |
| Optional filesystem path for SQLite storage (defaults to
). Accepts plain paths or
URLs; ensure the path resolves to persistent storage when using SQLite. |
/
| Optional listen port / host (defaults:
/
). |
ℹ️ Install the appropriate database driver when enabling persistence:
npm install better-sqlite3for SQLite,npm install pgfor PostgreSQL, ornpm install mysql2for MySQL/MariaDB.
Install & Build
Run
The server exposes two transports:
http://<host>:<port>/sse— SSE transport (compatible with Claude SSE etc.)http://<host>:<port>/mcp— Streamable HTTP transport (one-shot POST per exchange)
OAuth flow
Configure your client (e.g. ChatGPT custom connector) with:
Authorization URL:
https://your-domain.example.com/oauth/authorizeToken URL:
https://your-domain.example.com/oauth/tokenRevocation URL:
https://your-domain.example.com/oauth/revokeScopes: (leave blank)
PKCE: enabled (ChatGPT uses S256 automatically)
When prompted, the browser shows the RefMD MCP consent page. Paste a RefMD API token generated from Profile → API tokens and approve.
The connector receives an access token and can call
/sseor/mcpwithAuthorization: Bearer <token>.
Tokens can be revoked from RefMD (profile page) or via POST /oauth/revoke.
Run with Docker
Mount a persistent volume (as shown above) so the SQLite database file survives container restarts.
Connecting a Chat Client
Claude (CLI):
claude mcp add --transport sse refmd https://your-domain.example.com/sseCursor / VS Code / MCP Inspector: choose an SSE transport and supply the same URL.
Once connected, resources appear under refmd://document/{id}. Available tools include refmd-list-documents, refmd-search-documents, refmd-create-document, refmd-read-document, refmd-update-document-content, and more.
Release workflow
The GitHub Actions workflow CI MCP Server ships the container image. It runs automatically on pushes/PRs touching mcp-server and publishes to GHCR when:
the push is a tag matching
mcp-server-v*(versioned release), orthe workflow is manually triggered with
publish=true.
Tags published to ghcr.io/<owner>/refmd-mcp include semantic versions (1.2.0, 1.2, 1), the raw git tag, and latest. Use the extra-tag input for additional labels when invoking the workflow manually.
Development
Run in watch mode with TSX:
Any code changes require a rebuild (npm run build) before deploying or running with npm start.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables chatbots to browse, search, create, and edit Markdown documents stored in RefMD through a hosted SSE endpoint with OAuth 2.1 authentication.