Skip to main content
Glama

Quick start

Pick the path that matches what you want. Both start with no database to set up: state lives in a local SQLite file. You need Node 22.13 or later, or Docker.

You want

Start with

To click through it in a browser

npx @chnxthr/knowledge-mcp in any folder. The console opens

Your own tools (internal APIs, databases, anything)

npx create-knowledge-mcp my-mcp

Questions about your database or API, no code

Your data as tools: a connection and a query in the config

Only the built-in connectors (Drive, Slack, GitHub, Railway)

The Docker image

Your own tools

npx create-knowledge-mcp my-mcp
cd my-mcp
npm run dev                                                   # http://localhost:8080/mcp, reloads on save

The generator ends with a guided setup. It asks which services to connect, checks each key against the real service as you enter it, writes .env and mcp.config.json, creates the admin key and offers to add the server to Claude Code. Nothing is edited by hand, and you can run it again any time:

npm run setup

Or let an AI agent do it. The project includes AGENTS.md, a setup guide for agents: open the folder in Claude Code and say "set this server up, follow AGENTS.md". The agent runs the setup commands, asks before creating anything in your accounts, and never handles your secrets.

Search your documents first. A folder of documents is enough: no account and no key.

npm run setup -- folder ~/Documents/handbook   # Markdown, text, PDF, Word, PowerPoint, Excel
npm run dev

The server indexes the folder when it starts, and search_knowledge answers by keywords, in any language. An embedding model adds search by meaning later, without reading the documents again. Google Drive documents join the same index once Drive is connected.

The project comes with an example plugin, src/plugins/notes.ts. Point a client at http://localhost:8080/mcp with Authorization: Bearer <key> and you will see notes_add and notes_list.

Only the built-in connectors

cp .env.example .env                         # fill in the connectors you want
cp mcp.config.example.json mcp.config.json   # Drive folders, excluded folders, sign-in allowlist
docker run -d --name kmcp -p 8080:8080 -v kmcp-data:/data --env-file .env \
  -v "$PWD/mcp.config.json:/app/mcp.config.json:ro" ghcr.io/chanthr/knowledge-mcp:latest
docker exec kmcp knowledge-mcp keys create --email you@example.com --role admin
docker exec kmcp knowledge-mcp doctor        # which connectors are on, and what each one is missing

.env.example lists every variable. Each connector turns on when its variables are set. The image holds no config: mount mcp.config.json as above, or pass it inline with -e MCP_CONFIG_JSON='{…}'. compose.yaml does the same with Docker Compose.

Related MCP server: brkt-gdrive-mcp

The console

A page in your browser for everything the setup commands do. Start the server in a terminal and it prints the address:

npx @chnxthr/knowledge-mcp     # in any folder: the settings are saved there, and the console opens
npm run dev                    # in a generated project: the address is in the first lines

The console: what is connected and whether it works

The menu follows the order a server is set up in: what it reads, the models it uses, how search finds, and who may ask it. An old address (#/agent, #/data, #/graph, #/activity) opens the page that has it now.

Menu

Page

What you do there

Overview

The steps of setting up, each marked when done, and a live check of everything connected

Sources

Documents

Drop files or folders on the page to copy them in, add a folder where it is (pick it in the computer's own folder chooser, or type its path), connect Google Drive (sign in with Google, let gcloud make a service account, or paste a key), and read the scanned files waiting for OCR

Apps and data

Connect Slack, GitHub and Railway, by signing in where the app allows it or with a token. Add apps that have an MCP server of their own (Notion, Supabase, Linear, Sentry, …): you sign in at the app, and its read tools arrive under its name. Connect Postgres, SQLite or an HTTP API, and save a query as a tool: the page lists the tables and checks the query on the real database before it is saved

AI

Models

The language model (your ChatGPT Plus or Pro plan with Continue with ChatGPT, Claude, OpenRouter, OpenAI, a model on this machine through Ollama, or any endpoint that speaks OpenAI's chat completions), the embedding model for search by meaning, and the model that reads scans. Each is picked from the provider's own list and checked once before it is saved. Until one is connected the server calls none

Chat

Ask the language model, and watch it answer with this server's tools: each call and what it returned, as it happens. It gets the tools that only read and the instructions every client gets. Nothing is saved

Wiki

Pages the language model writes from your documents (below)

Search

Search

Passages: how documents are cut, and how well search finds them, measured on your documents. Links between documents: the links people wrote, the most linked documents, a view around any one, and the loose ends

Share

Connect

One button adds this server to Claude Code, Claude Desktop, Cursor or VS Code, and shows which already have it. A public address through Cloudflare for Claude on the web, ChatGPT and other people

Tools

Try a tool: fill in the form and run one to see what a client gets back. Recent calls: who, when, how long, and whether it worked

People and keys

Create and revoke keys, and limit a person to some tools

The console: trying a tool

A saved change takes effect by itself: the server starts again and the page waits for it. Every value is checked against the real service before it is written, to the same .env and mcp.config.json the commands write, so the console and the commands can be mixed freely.

Connecting without copying a token

Making a token in another site's settings and carrying it over is the slow part of setting up. Where a service offers something better, the console uses it:

Service

In the console

What it takes

Railway

Sign in with Railway

Nothing to prepare. The server registers itself with Railway, you sign in and pick the workspaces it may read, as a viewer. The sign-in renews itself. A viewer sees projects and deployments; Railway shows logs to members only, so Also read logs asks for member access instead (it could also change things; this server only reads)

Google Drive

Sign in with Google

An OAuth client of your own Google Cloud project, made once: client ID and secret go into the form. The server then reads your My Drive, or the folders you list, as you. Google reviews every shared app that reads Drive, which is why there is no ready-made one to offer

Google Drive

Account with gcloud

Nothing to prepare on a machine with Homebrew or winget: the console installs the gcloud CLI and runs its sign-in (a browser window opens). gcloud then creates a service account and its key; you share folders with that account. When Google asks an organization account to sign in again, the console runs the sign-in again

Notion, Supabase, Linear and other apps with an MCP server

Add an app

Nothing to prepare where the app's server follows MCP's sign-in rules: this server registers itself there and you sign in at the app. Only its tools that read are turned on, and Supabase is added in its read-only mode

GitHub

Connect with the gh CLI

Nothing to prepare on a machine with Homebrew or winget: one button installs the gh CLI, signs it in with a code you type at github.com, and uses its login. With gh already signed in it is Use the gh login

Slack

A link that opens Slack's "Create an app" with the read-only permissions filled in

The bot token is still copied once. Slack's sign-in needs a secret and a public https address, which a server on your machine has not

The console does not send you to a terminal for these tools. It runs the command itself and waits: brew install gh or brew install --cask gcloud-cli (winget on Windows), gcloud auth login, gh auth login --web. The page shows the command before an install and how far it is. Each command is fixed, and nothing typed into the page reaches a command line. Where there is no package manager it knows, it links to the tool's own instructions.

A token can still be pasted for each, and RAILWAY_TOKEN in the environment wins over a sign-in. With a personal Google account, publish the OAuth consent screen (it stays unverified, which is fine for your own use): left in "Testing", Google ends the sign-in every 7 days.

The console is for the person at the machine. It is served only when the server was started in a terminal (a service, a container or a process manager gets none unless KNOWLEDGE_CONSOLE=on), it answers only a browser on this machine that asks for localhost, and its API needs a token the server creates on first start (<data dir>/console-token) and prints as part of the address. The page never shows a secret: it says that a token is set, not what it is. Whoever holds the console token is the admin of this server, so keep it like a password. KNOWLEDGE_CONSOLE=off turns the console off.

Your ChatGPT plan as the model

On the Models page, choose ChatGPT account (Plus or Pro) and press Continue with ChatGPT. OpenAI opens in a new tab: sign in and allow Knowledge MCP. The models your plan includes are listed; pick one and save. No API key is needed, and nothing is billed apart from the plan.

How

OpenAI's sign-in for open-source apps on your own machine (guide): OAuth with PKCE, the browser comes back to http://127.0.0.1:<port>/console/login/chatgpt, the ID token is checked against OpenAI's keys

Usage

Counts against your plan. See it, and limit it for this app, in ChatGPT settings, Usage

Kept

chatgpt-account.json in the data directory, readable only by you. The access token is renewed before it runs out; .env holds only LLM_PROVIDER=chatgpt and LLM_MODEL

Sign out

In the same dialog. The session is ended at OpenAI and the tokens are deleted here

A Claude Pro or Max plan cannot be used the same way: Anthropic does not allow other apps to use a Claude subscription's sign-in. Use Claude with an API key, or connect this server to Claude instead (the Connect page).

A wiki written from your documents

Search finds passages again for every question. A wiki keeps what was understood. With a language model connected on the Models page, the server reads your documents and writes one, as plain Markdown in wiki/ beside your settings:

wiki/
  AGENTS.md    the rules of this wiki: what to take from a document, in which language. Yours to change
  index.md     every page with one line
  log.md       what was read, and when
  sources/     one page per document: what it says, and the topics it feeds
  topics/      one page per topic: what all the documents say about it, each fact with the document it is from

Start

Wiki → Create the wiki, then Read documents. A press reads up to 25 documents and says what it came to (questions asked, tokens in and out) before you read on

What it reads

The documents in your folders and in uploads/. They are never changed. A document is read again only when it has changed, and what a removed document said leaves the wiki with it

What it costs

One question to the model per document (more for a long one, read in parts), and one per topic page that at least three facts speak of

Where it shows up

The wiki is a folder of this server: search_knowledge and read_document find its pages, and Search → Links between documents and linked_documents follow its links, from a topic to its documents and back

Obsidian

Open wiki/ as a vault: pages link with [[…]], and file names are the titles

Your own notes

Whatever you write under a ## Notes heading on a page stays when the page is written again

A small or local model

Works: the model is asked for labelled lines, not JSON. Set WIKI_PART_CHARS (default 24000) lower when the model's window is small. What a page says is as good as the model that read the document

How it works

Part

What it does

You write it?

Core

HTTP and stdio transports, API keys, OAuth 2.1 with Google sign-in, roles, audit log, secret masking in logs

No

Plugins

One connector each: its tools, the env vars it needs, its permission group

Yes, one file per plugin

Gateway

Proxies other MCP servers (GitHub's, Notion's, yours) under a name prefix, read-only by default

Config only

Store

Keys, users, OAuth tokens, plugin state, audit log. SQLite file by default, Supabase optional

No

Step

Who

What happens

1

Client

Calls /mcp with Authorization: Bearer <API key or OAuth access token>.

2

Core

Checks the key against its stored hash, or verifies the OAuth token, then loads the person's role and limits.

3

Core

Lists only tools whose plugin is configured and that the person's role allows.

4

Plugin

Gets validated input and the caller, does the work, returns text or JSON. The call is logged.

Add a tool

Every file in src/plugins/ is a plugin. Copy the example and edit it:

// src/plugins/weather.ts
import { definePlugin, defineTool, ToolError, z } from '@chnxthr/knowledge-mcp';

export default definePlugin({
  id: 'weather',                    // also the permission group
  env: ['WEATHER_API_KEY'],         // the tools stay hidden until this is set
  tools: [
    defineTool({
      name: 'weather_now',
      description: 'Current weather for a city. Use it for questions about today’s weather.',
      input: z.object({ city: z.string().describe('City name, e.g. Seoul') }),
      annotations: { readOnlyHint: true },
      run: async ({ city }, ctx) => {
        const r = await fetch(`https://api.example.com/weather?q=${encodeURIComponent(city)}`, {
          headers: { Authorization: `Bearer ${process.env.WEATHER_API_KEY}` },
        });
        if (r.status === 404) throw new ToolError(`No city named ${city}`);
        ctx.log(`weather for ${city} by ${ctx.user.email}`);
        return r.json();            // any JSON value is sent as compact JSON
      },
    }),
  ],
});

Save the file and the dev server restarts. New files in src/plugins/ are picked up too. You did not touch a router, a tool list or a permission table.

The core does this for you

How

Lists the tool

From name, description and the zod input (zod 3 or 4), turned into JSON Schema

Hides it when not configured

Until every name in env is set, and enabled() returns true when you add one

Validates input

Bad input returns [invalid_input] tool '<name>': field: reason to the model, and run is not called

Checks permission

The plugin id is the permission group (see Access control)

Formats the result

A string becomes text, any other value becomes compact JSON (the reader is a model, and indentation is a third of an indented answer), an MCP result passes through

Handles errors

throw new ToolError('...') returns [error] .... Any other error returns [fatal] ...

Logs the call

Tool, person, role, success and duration go to the audit log. Arguments are not stored

Your data as tools

A database or an internal API becomes tools without a plugin file. Name the connection, then declare what may be asked of it. Both go in mcp.config.json; secrets stay in .env.

{
  "connections": {
    "shop": { "type": "postgres", "urlEnv": "SHOP_DATABASE_URL", "description": "Orders and customers" },
    "crm": { "type": "http", "baseUrl": "https://crm.example.com/api/v2", "headers": { "Authorization": "Bearer ${CRM_TOKEN}" } }
  },
  "tools": [
    {
      "name": "orders_by_customer",
      "connection": "shop",
      "description": "Orders of one customer, newest first. Use it for questions about what a customer bought.",
      "params": {
        "email": { "type": "string", "description": "Customer email" },
        "limit": { "type": "integer", "default": 20, "min": 1, "max": 100 }
      },
      "sql": "select id, total, status, created_at from orders where email = :email order by created_at desc limit :limit"
    },
    {
      "name": "crm_contact",
      "connection": "crm",
      "description": "One CRM contact by id.",
      "params": { "id": { "type": "string" } },
      "request": { "path": "/contacts/{id}", "pick": "data" }
    }
  ]
}
npm run setup -- connection shop --postgres --env SHOP_DATABASE_URL   # writes the connection
npm run setup -- secret SHOP_DATABASE_URL                             # you type the URL into .env, unseen
npm run setup -- check                                                # connects, and compiles every query

setup check connects to each database and compiles each declared query there, so a misspelled column is reported before the model ever calls the tool. Nothing is executed. The config is read at startup; npm run dev restarts when mcp.config.json or .env changes.

Or let the assistant write the queries. With "explore": true on a database connection two more tools appear: shop_tables lists the tables and columns, shop_query runs one read-only SELECT. The assistant can then answer questions nobody prepared a tool for. npm run setup offers this when you pick Database.

What keeps it safe

How

A value is never part of the SQL

Each :name is bound by the database driver. Whatever the caller passes is data

A read-only tool cannot write

Postgres: the query runs alone in a read-only transaction that is rolled back, and the server accepts one statement. SQLite: the file is opened read-only. Both refuse a write however the query is written

One question cannot take a table or the server

The row limit (maxRows, default 100) is applied by the database and the time limit (timeoutMs, default 10 s) stops the query. An answer is limited in size too: long values are cut at 4,000 characters, a Postgres result over 16 MB is dropped, and at most 4 SQLite queries run at once

An API tool stays on its API

A parameter fills one path segment, a query value, a header value or a JSON field. The host and base path are fixed, and redirects are not followed

A secret stays a secret

${ENV_NAME} values are masked wherever they show up in an answer, such as an API error that echoes the request. A parameter cannot pull one in: a value is never read as a template

Who may call it

The connection's name is a permission group like a plugin id (see Access control). A member without a tool list may use every group, a new connection included

What it can read

Whatever the database user can read, above all with explore. Give the connection a user of its own that can only read, and only what everyone using this server may see. Never a superuser, and not the user your application runs as: a query can end other sessions of its own user

Connection

Fields

postgres

urlEnv (the NAME of the env var holding postgres://user:password@host:5432/db), explore, maxRows, timeoutMs, pool (connections kept open, default 3), description

sqlite

path (absolute, or relative to the project), explore, maxRows, timeoutMs, description. Each query runs in a short-lived child process, so a slow one can be stopped, and it ends with the server instead of outliving it

http

baseUrl, headers and query sent with every request (a value may contain ${ENV_NAME}), timeoutMs (default 15 s), maxBytes (largest response read, default 1 MB), description

Tool field

Meaning

name, description

What the model sees. It picks tools by the description, so say what the tool answers and when to use it

connection

The connection it runs on

params

{ name: { type, description, required, default, enum, min, max, maxLength, pattern } }. type is string, integer, number or boolean. A parameter with a default is optional; an optional one without a value is NULL in SQL and left out of a request

sql

One statement with :name where a parameter goes (database connections)

request

{ method, path, query, headers, body, pick } (http connections). {name} puts a parameter in. In body, a string that is exactly {name} takes the parameter's own type. pick keeps one part of a JSON answer, such as data.items

readOnly

SQL: default true; set false for a tool that is meant to change data. HTTP: default true for GET; any other method has to say true or false

maxRows, timeoutMs

Override the connection's limits for this tool

Command

What it does

knowledge-mcp setup connection <name> --postgres --env NAME [--explore]

Add a Postgres connection. The connection string is never an argument

knowledge-mcp setup connection <name> --sqlite <file> [--explore]

Add a SQLite file

knowledge-mcp setup connection <name> --http <base URL> --header 'Authorization: Bearer ${API_TOKEN}'

Add an API. A header or query value that looks like a secret must be written as ${ENV_NAME}

knowledge-mcp setup secret <ENV_NAME>

Type one secret into .env without it being shown (needs a terminal)

knowledge-mcp <name> tables [filter]

The tables and columns the connection can read, for writing tools

knowledge-mcp <name> check

Check one connection and its tools

A mistake inside the config (a parameter the query does not use, a second statement, an unknown connection) stops the server at boot with the tool's name in the message. Postgres uses the pg driver, loaded on first use.

Plugin API

Everything is exported from @chnxthr/knowledge-mcp.

Field

Type

Meaning

id

string

Lowercase letters, digits and dashes. Permission group and config key

description

string

One line shown by knowledge-mcp doctor

env

string[]

Env vars that must all be set for the plugin to turn on

enabled

() => true | string

Extra condition. Return a reason string to stay off; doctor shows it

tools

Tool[]

Tools made with defineTool

upstreams

UpstreamSpec[] or a function

Remote MCP servers whose tools join this plugin's group (see Gateway)

instructions

string

Usage notes added to what the client receives on connect

configSchema

zod schema

Validates plugins.<id> in mcp.config.json; the result is ctx.config

start

(ctx) => void

Runs once after the HTTP server listens. For background jobs. Not run in stdio mode

commands

{ [name]: { description, run(args) } }

CLI commands: knowledge-mcp <id> <name> [args]

Field

Type

Meaning

name

string

Lowercase letters, digits and underscores. Unique across all plugins; ping is reserved

description

string

What it does and when to use it. The model picks tools by this

input

zod object

Arguments. Describe each field with .describe(). Omit for no arguments

annotations

ToolAnnotations

MCP hints such as readOnlyHint and destructiveHint

enabled

() => true | string

Extra condition for this one tool

run

(input, ctx) => value

Gets the parsed input and the context below

ctx.

Meaning

user

{ email, role, keyId }. Role is admin, member or viewer

state

get(key), set(key, value), delete(key). Kept per plugin in the store, so it survives restarts

config

This plugin's plugins.<id> section of mcp.config.json

log(...)

Writes to stderr with the plugin name. Secrets are masked. Never use console.log in stdio mode

auth

The full auth context, including Slack channel and Drive folder limits

A generated project has one entry file. It is also the command line, so every command sees your plugins.

import { run, builtinPlugins, loadPlugins } from '@chnxthr/knowledge-mcp';

const mine = await loadPlugins(new URL('./plugins/', import.meta.url));
await run({ plugins: [...builtinPlugins, ...mine] });

loadPlugins imports every .ts and .js file in the folder in name order. It skips names starting with _, .d.ts files and tests. Leave out builtinPlugins, or pick from knowledgePlugin, drivePlugin, slackPlugin, githubPlugin and railwayPlugin, to ship fewer connectors.

CLI

The knowledge-mcp binary, the Docker image entrypoint, and your own server.ts all take these commands.

Command

What it does

setup

Guided setup: connect Drive, Slack, GitHub and Railway, check every value live, write .env and the config, create the admin key. With gcloud installed it creates the Drive service account for you; with gh signed in it can reuse that login. Safe to run again

setup check

Verifies every configured service against the real thing. Exit code 1 on a failure

setup drive --gcloud [--project ID] [--yes]

Creates the Drive service account and key with the gcloud CLI. Prints its plan and creates nothing without --yes

setup trust <email-or-domain>...

Adds owners whose shared Drive documents are shown

setup folder <path>

Adds a local folder of documents to the search index

setup connection <name> --postgres --env NAME / --sqlite <file> / --http <base URL>

Adds a database or an API for tools declared in the config (see Your data as tools)

setup secret <ENV_NAME>

Types one secret into .env without it being shown

setup drive --key <file> / setup github --from-gh / setup embeddings --base-url URL --model NAME

Setup steps that ask nothing, for scripts and AI agents

serve

Starts the HTTP server on $PORT (default 8080). Started in a terminal it also serves the console at /console/ and restarts itself when the console saves a change; --open opens the console in the browser, and so does running with no command at all. serve --stdio talks over stdin and stdout instead

keys create [--email E] [--role R] [--label L] [--expires 90d]

Creates an API key and prints it once. Only its hash is stored

keys list / keys revoke <id>

Lists keys (never the key itself) or deactivates one

users add <email> [--role admin|member] [--tools a,b]

Registers a person. --tools limits a member to those plugins

users list / users remove <email>

Shows or removes people

doctor

Config source, store, OAuth, and each plugin on or off with the reason

<plugin> <command>

A plugin command, e.g. drive reindex --dry-run, slack channels, or for a connection shop tables

Built-in plugins

Each turns on when its env vars are set. All built-in tools only read.

Plugin

Tools

Needs

knowledge

search_knowledge, read_document, linked_documents

A local folder (folders in the config) or Google Drive. Nothing else: the index is a local file and search works by keywords. An embedding model (OPENAI_API_KEY, or another provider through EMBEDDING_BASE_URL) adds search by meaning. With QDRANT_URL vectors live in Qdrant and an embedding model is required

drive

search_drive, read_drive_file, list_drive_folder

A Google sign-in from the console (it reads your own Drive), or a service account: share a folder or a document with that account and it is searchable. An OAuth refresh token in the environment works too

slack

slack_list_channels, slack_read_channel, slack_find_files, slack_get_file

SLACK_BOT_TOKEN (xoxb-). The bot sees only channels it was invited to

slack

slack_search

SLACK_USER_TOKEN (xoxp-) as well. Results are limited to the bot's channels

github

repo_tree, plus GitHub's remote MCP tools as github_* (read-only)

GITHUB_PAT (or GITHUB_TOKEN) with Contents: read

railway

railway_services, railway_deployments, railway_logs (secrets in logs are masked)

A sign-in from the console, or RAILWAY_TOKEN. A sign-in asks for viewer access: it lists projects and deployments, and Railway does not show it logs. Logs need a token

core

ping

Nothing. Shows who you are and which plugins are on

search_knowledge searches one index that every source feeds. It needs nothing but a source.

Search mode

When

What it finds

Keywords

Always, with nothing configured

Documents that contain the words of the question. Korean, Japanese and Chinese are matched by character pairs, so a word is found with any ending attached

Keywords + meaning

An embedding model is set (OPENAI_API_KEY, or EMBEDDING_BASE_URL for another provider or a local model)

Also documents that say the same thing in other words. The two result lists are merged by rank. When the embedding endpoint is down, search answers from keywords and says so

Meaning only

QDRANT_URL is set

Vectors live in Qdrant, which holds no keyword index here. An embedding model is required

What the model reads is kept short, because it pays for every line:

Tool

What comes back

search_knowledge

Up to topK parts (default 5, at most 2 per document), each with the document, its date, an ID, the heading and how many terms of the question it holds. Two parts that are neighbours in a document are shown as one passage. When no passage holds half of the terms, the answer says the match is weak. A filter that matches nothing answers with the values that field has

read_document

With part (the number a result shows): that passage and the parts around it (around, default 1), a few thousand characters. Without it: the document from the start, up to maxChars (default 20,000), and the offset that continues it. Plain text, not JSON

linked_documents

With a document ID: what it links to and what links to it, by title, each with its ID. Without one: how many documents and links there are, and the documents most others link to. A search result that has links says so (Links: to 2 · from 3)

A tool on a database

Rows as a compact table: {"rowCount":2,"columns":["id","total"],"rows":[[1,10.5],[2,20]]}, one row per line. The column names are said once

The knowledge graph. Documents in the local folders are linked the way their authors linked them, with no model in between: [[Note]], [[Note|shown text]] and [[folder/Note#Heading]] as Obsidian writes them, Markdown links to documents ([guide](../guides/setup.md)), and header fields that name documents (related: [a.md, "[[Note]]"]). So an Obsidian vault added as a folder brings its graph with it. A target finds its document by path, by file name anywhere in the folder, or by title and alias; a note written later makes yesterday's dangling link whole. Only links that plainly meant a document and match none are reported as broken.

Task

How

Add a local folder

knowledge-mcp setup folder <path>, or folders in the config. The HTTP server scans it at start and every 10 minutes (KNOWLEDGE_SCAN_INTERVAL_MIN); a stdio session scans once when it starts; knowledge-mcp knowledge scan scans now. Unchanged files are not opened, deleted files leave the index. Text is indexed first and vectors afterwards, so keyword search covers the folder within seconds

Add Drive documents

Connect Drive. The server builds the first index when it starts with an empty one (DRIVE_AUTO_INDEX=false turns that off), then syncs changes every 30 minutes (DRIVE_SYNC_INTERVAL_MIN); a stdio session syncs once when it starts

Add search by meaning later

Set the embedding model and restart. Stored passages get their vectors on the next scan or sync; no document is read again

Change the embedding model

Set the new model, then knowledge-mcp knowledge reembed: it drops the old vectors and makes new ones from the stored text. Until then search answers by keywords, because vectors of two models are never mixed

What leaves the machine

Nothing for keyword search. With an embedding model, passage text and each question go to that model's endpoint

Where it lives

<data dir>/vectors.db: the text, the keyword index and the vectors. Measured with 90,000 passages (5,000 files): a keyword search takes about 6 ms, a search by meaning about 85 ms, and the vectors take about 4 bytes × dimensions per passage in memory (370 MB at 1,024 dimensions), read on the first search by meaning. Set QDRANT_URL (and reindex) for larger indexes or several servers

Scanned files

A folder scan never reads scans itself: it counts them. Reading them is a run of its own, started under Documents → Scanned files in the console (or after each scan, for an OCR on this computer when you turn that on). What was read is kept, so a scan is not read again while the file is unchanged. knowledge-mcp drive reindex reads scanned Drive files when an OCR is set (--no-ocr leaves them out)

Clean up

A full drive reindex deletes Drive documents no longer listed, such as files moved into an excluded folder

Start over

drive reindex --recreate empties the index first, local folders included (they are indexed again by the next scan). --dry-run only counts passages and skips OCR

A lock file keeps two processes on one data directory from indexing at the same time.

Format

How text is extracted

Markdown, plain text

As is

Google Docs, Slides

Drive export

Google Sheets

Drive export, every tab as its own section

Word, PowerPoint, Excel, PDF with text

Local parsers

Scanned PDF, PNG, JPEG, WebP

OCR, when one is set: each page is drawn and read by a vision model (a model on this computer through Ollama, Hugging Face Inference Providers, or any endpoint that speaks OpenAI's chat completions with images), or by Mathpix. Images in local folders are listed only while an OCR is set

Reading scanned documents (OCR). Under Documents → Scanned files in the console, choose what reads them:

Choice

What it is

This computer

A vision model in Ollama. The console fetches the model. Pages never leave the computer and nothing is billed

Hugging Face

Inference Providers (https://router.huggingface.co/v1) with a token. Pages go to Hugging Face and the partner that runs the model

Another endpoint

Any API that speaks OpenAI's chat completions and takes images: OpenRouter, vLLM, LM Studio

Mathpix

As before: MATHPIX_APP_ID, MATHPIX_APP_KEY

Before a model is saved it has to read a test page back. In the config it is OCR_PROVIDER (model or mathpix), OCR_BASE_URL, OCR_API_KEY, OCR_MODEL and OCR_PROMPT (glm-ocr and deepseek-ocr get the prompt their model card gives). OCR_MAX_PAGES (200) caps the pages read from one file. Measured on 16 Korean PDF pages whose text is known, read through Ollama on an Apple Silicon Mac:

Model

Characters wrong (median a page)

Seconds a page

qwen3-vl:8b-instruct

about 1 in 100

15

glm-ocr:q8_0

about 1 in 10

6

deepseek-ocr:3b

about 4 in 100, but 5 of the 16 pages came back as one phrase repeated

8

Files larger than DRIVE_MAX_FILE_BYTES (50 MB by default) are not read or indexed. In a local folder, dot files, node_modules, the folder names in drive.excludeFolders and symbolic links are skipped, and at most 20,000 files per folder are indexed (KNOWLEDGE_MAX_FILES). Embeddings use OpenAI text-embedding-3-small by default. Any OpenAI-compatible /embeddings endpoint works: set EMBEDDING_BASE_URL, EMBEDDING_MODEL and EMBEDDING_DIM (for example a local bge-m3 behind Ollama).

How passages are made. What search finds depends on how documents are cut, and which way is best depends on the documents. Choose it under Documents → Passages in the console, and compare the ways on your own documents there first. In the config it is knowledge.index:

Setting

Values

Default

cut

sections: at headings, then at paragraphs when a section is long. windows: by length, headings ignored

sections

maxTokens

The most tokens in a passage, 100 to 4,000

800

overlapTokens

Tokens repeated from the passage before

An eighth of a passage, at most 100

header

What the embedding model reads with each passage: heading (its heading path), document (the document's name and the heading path) or none

heading

queryPrefix, passagePrefix

Put before each question and before each passage

The model's own, when it is known

Environment variables win over the config: KNOWLEDGE_CHUNK_CUT, KNOWLEDGE_CHUNK_TOKENS, KNOWLEDGE_CHUNK_OVERLAP, KNOWLEDGE_EMBED_HEADER, EMBEDDING_QUERY_PREFIX, EMBEDDING_PASSAGE_PREFIX. The prefixes an embedding model was trained with are known by its name for qwen3-embedding, e5, nomic-embed-text, embeddinggemma, mxbai-embed-large and bge-*-en, as their model cards give them. Other models get none unless you set them. With Qdrant a passage prefix is never added by itself.

What changed

What happens

cut, maxTokens, overlapTokens

Documents in local folders are cut again by the next scan, which starts when the console saves. Drive documents are cut again when they change, or all at once with drive reindex

header, the passage prefix

Every passage needs a new vector: Make new vectors in the console, or knowledge reembed. Until then new passages and questions are embedded the way the stored vectors were. The two are never mixed

Command

What it does

knowledge-mcp knowledge measure

Asks questions whose answer is known of the index as it is, and counts where the right document comes by keywords, by meaning and with both

knowledge-mcp knowledge compare

Cuts up to 200 documents from the local folders each way, embeds them in memory and asks the same questions by meaning. The index is not changed

The questions are written by the language model connected on the Models page, one from each of 40 documents, and kept in <data dir>/search-measure.json: every run asks the same ones, so results can be set side by side. Write your own there instead if you like ({"questions":[{"question":"…","document":"a part of its path"}]}); --new writes new ones. Measured on a wiki of 503 Markdown files with qwen3-embedding:0.6b and 84 questions: 250 to 800 tokens at headings found about the same (the right document among the first three for 71 to 75), cutting by length found less, and the model's own prefix on questions put the right document first for 48 instead of 43.

slack_list_channels tells the model what each channel is for.

  1. Invite the bot to the channels it should read, then call slack_list_channels once from a client. That call copies the channel list from Slack into the map. New channels arrive switched off.

  2. Describe a channel and switch it on: knowledge-mcp slack channel '#dev' --purpose "Deploys and incidents" --on. List the map with knowledge-mcp slack channels.

On and off only decide what slack_list_channels shows by default. They do not grant or block reading: that depends on the bot's channels and on each person's allowed channels.

Configuration

Layer

Where

What

Secrets

Env vars (.env locally, host env in production)

Keys and tokens. .env.example lists them all

What to look at

mcp.config.json

Drive folders, exclusions, sign-in allowlist, viewer access, plugin settings, remote MCP servers. See mcp.config.example.json

.env and mcp.config.json are read from the working directory first, then from your project folder, so a client that starts the server from elsewhere still finds them. MCP_CONFIG_JSON (inline) and MCP_CONFIG_PATH override the file. MCP_HOME names the folder of the settings and the data outright; the working directory is then not looked at, which is what a client's entry needs when the server is started through npx from somebody else's project. The config is read once at startup: restart the server after you change it, the sign-in allowlist included. (A server started in a terminal restarts itself when the console saves a change.)

Config key

Meaning

orgId

Organization identifier carried in the auth context

branding.name / branding.instructions

Name shown on the sign-in consent page and in OAuth metadata. instructions replaces the guide the client receives (base line plus each plugin's notes)

folders[]

{ path, name, source } local folders to index and search. path is absolute or relative to the config file. name (default: the folder's own name) shows in results and document ids; source (default files) is the label for the source search filter. env KNOWLEDGE_FOLDERS adds comma-separated paths

drive.roots[]

{ id, name, source, metadata } folders to index and search. source is a label you choose (handbook, sales, …; default docs) and becomes the source search filter. metadata is path (default: category, customer and tags from folder and file names) or frontmatter (Markdown with a YAML header)

drive.scope

shared (default): the roots plus any folder or document that a trusted owner (drive.trustedOwners) shared with the service account. roots: only files under drive.roots. env DRIVE_SCOPE overrides

drive.trustedOwners[]

Whose documents are shown when they are shared with the service account outside the roots: emails (ann@acme.com), domains (acme.com) or shared drives (drive:<id>). Empty by default, which shows nothing outside the roots. knowledge-mcp setup asks for it. env DRIVE_TRUSTED_OWNERS overrides

drive.sharedSource

source label for documents shared outside the roots. Default shared

drive.excludeFolders[]

Folder names skipped everywhere, in Drive and in local folders: index, search, read and list. Case and spacing are ignored

drive.customerFolders[]

Top-level folders (in path metadata sources) with one subfolder per customer (Clients/Acme/… → customer Acme), for the customer search filter. Default Clients, Customers, 고객사

drive.rank[]

Optional { prefix, label, weight } rules for search_knowledge, e.g. prefer Current/ (weight 1.1) over Archive/ (0.9). Default: none

qdrant.collection

Vector collection name (env QDRANT_COLLECTION overrides)

oauth.allowedDomains[] / oauth.allowedEmails[]

Who may sign in with Google

access.viewerTools[]

Plugin ids open to signed-in people without a users entry. Default: none

plugins.<id>

Settings for one plugin, passed as ctx.config

upstreams[]

Remote MCP servers (next section)

connections.<name>

A Postgres database, a SQLite file or an HTTP API. The name is the permission group. See Your data as tools

tools[]

Tools declared on a connection: one SQL query or one API request each, with typed parameters

data.schema

Supabase schema for the server's tables (Supabase store only)

Store

When

Setup

SQLite (default)

One server, one machine

Nothing. The file is <data dir>/knowledge-mcp.db (MCP_DATA_DIR, /data in Docker). Created owner-only (0600)

Supabase

State in a shared Postgres you can browse

Run sql/supabase.sql (again after every upgrade), set SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY

Setting both Supabase variables selects Supabase. MCP_STORE=sqlite|supabase forces one.

Remote MCP servers

The server can also be a gateway: list another MCP server and its tools appear under a prefix, behind your keys and permissions.

In the console this is Apps → Add an app: pick from the list (Notion, Supabase, Linear, Atlassian, Sentry, Vercel, Stripe, Airtable, Figma and more) or give the address of any MCP server. When the server says where to sign in and lets a client register itself, you are sent there to sign in; a token can be pasted where the service gives one. By hand, in mcp.config.json:

{
  "upstreams": [
    {
      "name": "notion",
      "url": "https://mcp.example.com/mcp",
      "tokenEnv": "NOTION_MCP_TOKEN",
      "expose": "read"
    }
  ]
}

Field

Meaning

name

Permission group and log name

prefix

Tool name prefix. Default <name>_

tokenEnv

Env var holding the bearer token. The token never goes in the config file

signIn

true: use the sign-in made from the console (<data dir>/mcp-logins/<name>.json). The gateway renews it by itself. Not together with tokenEnv

expose

"read" (default) lists only tools that read: the ones the remote marks as read-only, and of those it does not mark, the ones whose first word is a read verb such as get, list or search (notion-search counts as search). A tool the remote marks as changing things stays hidden whatever its name. "all" lists everything. A list exposes exactly those remote tool names

If a remote tool has the same name as a local one, the local tool wins and the remote one is hidden.

Access control

Who someone is comes from an API key or a Google sign-in. What they can use comes from their users entry.

Users entry

Role

What they can use

--role admin

admin

Every tool

--role member

member

Every plugin, unless --tools lists the ones they may use. Drive folders and Slack channels can be limited too

No entry

viewer

Only ping, plus the plugins in access.viewerTools

knowledge-mcp users add lee@example.com --role member --tools drive,notes
knowledge-mcp keys create --email lee@example.com --expires 90d
  1. Keys look like kmcp_… and are stored only as SHA-256 hashes. The key is shown once.

  2. A key with an email takes the person's role from their users entry, so removing the entry demotes the key. A key without an email is a service key with its own role.

  3. keys revoke <id> takes effect within AUTH_CACHE_TTL_MS (60 seconds by default).

  4. Failed authentication is rate-limited per client IP. Set TRUST_PROXY to match your proxy so the IP is real.

  5. stdio runs as the local admin unless MCP_API_KEY is set, because whoever starts the process already holds every token in its env.

Set the OAuth variables and an allowlist to turn on a built-in OAuth 2.1 server that signs people in with Google. It shows a consent page naming the app and where the token goes before anything is issued. The full guide is OAUTH_SETUP.md.

Deploy

What

How

Built-in connectors

ghcr.io/chanthr/knowledge-mcp (latest = newest release, x.y.z, edge = main). compose.yaml runs it with a data volume

Your own project

docker build with the generated Dockerfile, then run it with a volume at /data

Railway

railway.toml. Add a volume at /data, or set MCP_STORE=supabase

From your own machine

A Cloudflare Tunnel, set up in the console (below). The server, the documents and the index stay where they are

  1. HTTPS. Put the server behind HTTPS before remote clients connect. OAuth needs an https issuer.

  2. One replica. Sessions and pending sign-ins live in memory, and SQLite is one file. Run a single instance.

  3. Keep /data. Without a volume, keys and users are lost on redeploy.

A public address from your own machine

The server does not have to move anywhere to be reached from outside. Connect → Claude on the web, ChatGPT, other people in the console gives it an https address through a Cloudflare Tunnel: cloudflared, Cloudflare's program, connects out from your machine, so there is nothing to open in a router and no certificate to make.

A temporary address

Your own address

Looks like

https://<words>.trycloudflare.com

https://mcp.example.com

Needs

Nothing

A domain in a Cloudflare account. The console checks the address, then runs cloudflared tunnel login: the browser opens and you pick that domain

Lasts

Until it is stopped. New each time

It stays the same, and comes back when the server is started again

For

Trying it out. Cloudflare gives no guarantee for it and it carries no long-lived streams

Other people, Claude on the web, ChatGPT

The console installs cloudflared where there is Homebrew or winget, makes the tunnel and its DNS record, and starts it. Before anything is made in your account it checks the address: its domain must be on Cloudflare (public DNS says so), and the sign-in must be for that domain (Cloudflare's API, asked with the sign-in's own token, says which one it is; a sign-in is for one domain). After the record is made, what cloudflared says it made is compared with what was asked for, and the address counts as working only once https://<address>/health answers from outside. A DNS record that already exists under that name is not written over.

What does not change: /mcp asks for a key or a sign-in as before, and the console answers on your machine only (through the tunnel it answers 403). Your own cloudflared setup is not read, used or changed: not ~/.cloudflared/config.yml, not your other tunnels, and not the certificate of your own cloudflared tunnel login. This server signs in for itself (cloudflared runs with HOME in the data directory), and its tunnel has a config file and credentials of its own there. Signing out in the console deletes that file; the token in it stays valid until you delete it in the Cloudflare dashboard (My Profile, API Tokens).

Connect a client

The console's Connect page does this for you: one button per client, with the entry made for your folder and your server name. A desktop app does not have the PATH of your terminal, so the entry it writes names Node by its full path and the server starts there too.

Client

How

Claude Code, local

claude mcp add my-mcp -- node /abs/path/my-mcp/dist/server.js serve --stdio (run npm run build first)

Claude Code, local, without a project

claude mcp add --scope user my-mcp -e MCP_HOME=/abs/path/folder -- npx -y @chnxthr/knowledge-mcp serve --stdio

Claude Desktop, Cursor, VS Code, local

The same command and MCP_HOME in the client's config file, under command, args and env

Claude Code, remote

claude mcp add --transport http my-mcp https://<host>/mcp --header "Authorization: Bearer <key>"

Claude and ChatGPT connectors

Console → Connect: your own address, then Sign-in for connectors → Turn on. Add a custom connector with https://<host>/mcp; it asks for a key once (OAUTH_SETUP.md)

Any MCP client

URL https://<host>/mcp with header Authorization: Bearer <key>

Upgrading from 0.3

Change

What to do

Drive scope is shared by default

Documents that a trusted owner shared with the service account outside drive.roots can be searched, read and indexed. Nothing changes until you list owners in drive.trustedOwners (knowledge-mcp setup trust acme.com). Excluded folders stay hidden. drive.scope: "roots" turns it off

zod 4

Plugins get zod 4 through the exported z. Change z.record(valueSchema) to z.record(z.string(), valueSchema); an object .default({}) that relies on inner defaults becomes .prefault({})

source is a free label

dev and biz keep working with their old meaning. --dev-only and --biz-only still work; the general form is --source <label>

Google Sheets are read tab by tab

Indexed sheets change on their next modification. Run knowledge-mcp drive reindex to refresh them all now

semantic_search_drive is now search_knowledge

It searches every source, by keywords with no embedding model. Its permission group is knowledge: add knowledge where a person's tools or access.viewerTools list drive. read_document reads a result by its Document ID

Search shows at most 2 passages per document

Set KNOWLEDGE_MAX_PER_DOC to change it

Upgrading from 0.2

Change

What to do

Supabase is optional; SQLite is the default

Existing installs with SUPABASE_* set keep using Supabase. Rerun sql/supabase.sql once: it adds mcp_plugin_state and copies the Drive sync token

Commands moved into the CLI

npm run reindex → knowledge-mcp drive reindex. The image entrypoint is now knowledge-mcp (default serve) instead of node dist/index.js

Role engineer is now member

Existing rows keep working. access.viewerTools and allowed_tools take any plugin id

stdio without MCP_API_KEY

Runs as the local admin instead of refusing to start

Broken mcp.config.json

Now stops the server with the parse error instead of silently using defaults

Security notes

  1. Never commit .env, service-account JSON, mcp.config.json or data/. All are gitignored and kept out of the image.

  2. The data file holds key hashes and OAuth client secrets. It is created owner-only; keep the volume private.

  3. Built-in plugins never change Drive, Slack, GitHub or Railway. The gateway exposes remote write tools only if you set expose.

  4. Drive indexing sends document text to the embedding provider (OpenAI by default; your own server when EMBEDDING_BASE_URL is set), and scanned files to Mathpix when OCR is on. A language model connected on the Models page is sent the text of your documents while you chat or the wiki is written, and at no other time. Connecting it sends one short question to check the key. The key is in .env (LLM_PROVIDER, LLM_API_KEY, LLM_BASE_URL, LLM_MODEL) and is never sent back to the page. A ChatGPT sign-in is kept in chatgpt-account.json in the data directory (owner only), and never sent to the page either.

  5. Anyone who knows the service account's address can share a document with it; Drive asks nobody. So a document shared outside the roots is shown only when the top shared item belongs to an owner in drive.trustedOwners. Keep that list to your own organization, never *. What a trusted owner shares is visible to every user who may use the drive tools: list sensitive folder names in drive.excludeFolders.

  6. A token reaches whatever it can read. Scope the Slack bot, the GitHub token and the Railway token to what every user may see.

  7. A database connection reads whatever its database user can read. Give it a user of its own that can only read: never a superuser, not the user your application runs as, and with explore only one that sees what every permitted person may see. A member without a tool list may use every connection.

  8. The console changes settings and runs tools as the admin, so it is kept to the person at the machine. It exists only when the server was started in a terminal or with KNOWLEDGE_CONSOLE=on. Requests from another address, with a forwarding header, under a host name other than localhost, or marked by the browser as coming from another site are refused; the API needs the console token; the page loads nothing from outside the server. Two limits to know: a reverse proxy on the same machine that adds no forwarding header (nginx's plain proxy_pass) looks like a local browser, so on a server leave the console off; and every user of a shared machine can reach localhost, where the owner-only token file is what keeps them out.

  9. The console token is the admin's key. Its holder can change every setting, and can declare a connection that sends a secret from .env to an address of their choosing (that is what a connection is). The console narrows this to secrets in the folder's .env: it refuses a ${NAME} that names one of the server's own credentials or a variable the server only inherited from the shell.

  10. A sign-in made from the console is kept in the data directory (railway-login.json, google-login.json, mcp-logins/), readable by the owner only, like the data file. A Google sign-in reads as you: whatever is in the folders you chose is visible to every user of the server, so choose folders meant for all of them. The address the browser comes back to after a sign-in accepts only the answer to a sign-in the console started minutes before, and saves nothing by itself.

  11. An app added through its MCP server acts as the account that signed in, for every user who may use that app's tools here. Only tools that read are on unless you allow changes, and what counts as reading is the app's own word about each tool, so add servers you trust. What its tools return is the app's text, not instructions.

File map

Path

Contents

packages/knowledge-mcp/src/plugin/

Plugin API: definePlugin, defineTool, registry, loader, result formatting

packages/knowledge-mcp/src/core/

Auth, OAuth, permissions, config, gateway, log masking

packages/knowledge-mcp/src/server/

HTTP and stdio transports, MCP request handling, identity

packages/knowledge-mcp/src/store/

Store interface, SQLite and Supabase implementations

packages/knowledge-mcp/src/plugins/

Built-in plugins: knowledge, drive, slack, github, railway

packages/knowledge-mcp/src/connections/

Tools declared in the config: Postgres, SQLite and HTTP connections

packages/knowledge-mcp/src/admin/

The console's API, its access rules, and the supervisor that restarts the server after a saved change

packages/knowledge-mcp/console/

The console page (React). Built into dist/console-ui; its controls are affectUI components, copied under src/ui (MIT, see the notice there)

packages/knowledge-mcp/src/run.ts

The command line

packages/knowledge-mcp/test/

Unit tests and end-to-end tests over HTTP and stdio

packages/create-knowledge-mcp/

The generator and its project template

scripts/smoke-create.sh

Pack, scaffold, install, build, serve and call, end to end

Dockerfile, compose.yaml, railway.toml

Image, local stack, Railway

.github/

CI, image and npm workflows, issue and PR templates, README images (assets/make.py)

Develop with npm install, npm test (unit and end-to-end), npm run typecheck and npm run smoke:create.

Contributing

Please open an issue for problems and ideas. CONTRIBUTING.md has the setup, the checks to run and how to add a plugin. Changes per version are in CHANGELOG.md.

Template

Use it when

Bug report

Something behaves differently from the code or the docs

Improvement

You have a better way, or a doc no longer matches the code

This repository is public. Leave API keys, tokens, internal URLs and private documents out of issues and pull requests. Report security problems privately with Report a vulnerability on the Security tab, not in an issue.

License

MIT © chanthr

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

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI applications to access and contextualize organizational knowledge sources including GitHub repositories and internal documentation through standardized MCP protocol integration. Features OAuth 2.1 authentication, vector-based semantic search, and optimized context chunking for enterprise development workflows.
      -
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that enables LLMs to search, fetch, and act on Google Workspace (Drive, Gmail, Docs, Sheets, etc.) with rich, one-call results and file deposits to disk, reducing context usage.
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Exposes internal databases, HTTP APIs, and files to LLM agents over MCP, with auto-generated schemas, access controls, rate limiting, redaction, and audit logging.
      3
      MIT