Knowledge MCP
Explore private repository structure and use GitHub MCP tools.
Search, read, list, and semantically search files in Google Drive.
Inspect Railway services, deployments, and logs.
Search messages, read channels, list channels, and find files in Slack (read-only).
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
|
Your own tools (internal APIs, databases, anything) |
|
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 saveThe 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 setupOr 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 devThe 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 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 |

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 |
Usage | Counts against your plan. See it, and limit it for this app, in ChatGPT settings, Usage |
Kept |
|
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 fromStart | 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 |
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: |
Obsidian | Open |
Your own notes | Whatever you write under a |
A small or local model | Works: the model is asked for labelled lines, not JSON. Set |
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 |
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 |
Hides it when not configured | Until every name in |
Validates input | Bad input returns |
Checks permission | The plugin |
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 |
|
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 querysetup 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 |
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 ( |
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 |
|
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 |
Connection | Fields |
|
|
|
|
|
|
Tool field | Meaning |
| What the model sees. It picks tools by the description, so say what the tool answers and when to use it |
| The connection it runs on |
|
|
| One statement with |
|
|
| SQL: default |
| Override the connection's limits for this tool |
Command | What it does |
| Add a Postgres connection. The connection string is never an argument |
| Add a SQLite file |
| Add an API. A header or query value that looks like a secret must be written as |
| Type one secret into |
| The tables and columns the connection can read, for writing tools |
| 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 |
|
| Lowercase letters, digits and dashes. Permission group and config key |
|
| One line shown by |
|
| Env vars that must all be set for the plugin to turn on |
|
| Extra condition. Return a reason string to stay off; |
|
| Tools made with |
|
| Remote MCP servers whose tools join this plugin's group (see Gateway) |
|
| Usage notes added to what the client receives on connect |
| zod schema | Validates |
|
| Runs once after the HTTP server listens. For background jobs. Not run in stdio mode |
|
| CLI commands: |
Field | Type | Meaning |
|
| Lowercase letters, digits and underscores. Unique across all plugins; |
|
| What it does and when to use it. The model picks tools by this |
| zod object | Arguments. Describe each field with |
|
| MCP hints such as |
|
| Extra condition for this one tool |
|
| Gets the parsed input and the context below |
| Meaning |
|
|
|
|
| This plugin's |
| Writes to stderr with the plugin name. Secrets are masked. Never use |
| 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 |
| Guided setup: connect Drive, Slack, GitHub and Railway, check every value live, write |
| Verifies every configured service against the real thing. Exit code 1 on a failure |
| Creates the Drive service account and key with the gcloud CLI. Prints its plan and creates nothing without |
| Adds owners whose shared Drive documents are shown |
| Adds a local folder of documents to the search index |
| Adds a database or an API for tools declared in the config (see Your data as tools) |
| Types one secret into |
| Setup steps that ask nothing, for scripts and AI agents |
| Starts the HTTP server on |
| Creates an API key and prints it once. Only its hash is stored |
| Lists keys (never the key itself) or deactivates one |
| Registers a person. |
| Shows or removes people |
| Config source, store, OAuth, and each plugin on or off with the reason |
| A plugin command, e.g. |
Built-in plugins
Each turns on when its env vars are set. All built-in tools only read.
Plugin | Tools | Needs |
|
| A local 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 |
|
|
|
|
|
|
|
|
|
|
| A sign-in from the console, or |
core |
| 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 ( | 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 |
| 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 |
| Up to |
| With |
| 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 ( |
A tool on a database | Rows as a compact table: |
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 |
|
Add Drive documents | Connect Drive. The server builds the first index when it starts with an empty one ( |
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 |
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 |
|
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. |
Clean up | A full |
Start over |
|
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 ( |
Another endpoint | Any API that speaks OpenAI's chat completions and takes images: OpenRouter, vLLM, LM Studio |
Mathpix | As before: |
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 |
| about 1 in 100 | 15 |
| about 1 in 10 | 6 |
| 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 |
|
|
|
| The most tokens in a passage, 100 to 4,000 | 800 |
| Tokens repeated from the passage before | An eighth of a passage, at most 100 |
| What the embedding model reads with each passage: |
|
| 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 |
| 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 |
| Every passage needs a new vector: Make new vectors in the console, or |
Command | What it does |
| 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 |
| 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.
Invite the bot to the channels it should read, then call
slack_list_channelsonce from a client. That call copies the channel list from Slack into the map. New channels arrive switched off.Describe a channel and switch it on:
knowledge-mcp slack channel '#dev' --purpose "Deploys and incidents" --on. List the map withknowledge-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 ( | Keys and tokens. |
What to look at |
| Drive folders, exclusions, sign-in allowlist, viewer access, plugin settings, remote MCP servers. See |
.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 |
| Organization identifier carried in the auth context |
| Name shown on the sign-in consent page and in OAuth metadata. |
|
|
|
|
|
|
| Whose documents are shown when they are shared with the service account outside the roots: emails ( |
|
|
| Folder names skipped everywhere, in Drive and in local folders: index, search, read and list. Case and spacing are ignored |
| Top-level folders (in |
| Optional |
| Vector collection name (env |
| Who may sign in with Google |
| Plugin ids open to signed-in people without a users entry. Default: none |
| Settings for one plugin, passed as |
| Remote MCP servers (next section) |
| A Postgres database, a SQLite file or an HTTP API. The name is the permission group. See Your data as tools |
| Tools declared on a connection: one SQL query or one API request each, with typed parameters |
| Supabase schema for the server's tables (Supabase store only) |
Store | When | Setup |
SQLite (default) | One server, one machine | Nothing. The file is |
Supabase | State in a shared Postgres you can browse | Run |
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 |
| Permission group and log name |
| Tool name prefix. Default |
| Env var holding the bearer token. The token never goes in the config file |
|
|
|
|
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 |
| admin | Every tool |
| member | Every plugin, unless |
No entry | viewer | Only |
knowledge-mcp users add lee@example.com --role member --tools drive,notes
knowledge-mcp keys create --email lee@example.com --expires 90dKeys look like
kmcp_…and are stored only as SHA-256 hashes. The key is shown once.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.
keys revoke <id>takes effect withinAUTH_CACHE_TTL_MS(60 seconds by default).Failed authentication is rate-limited per client IP. Set
TRUST_PROXYto match your proxy so the IP is real.stdio runs as the local admin unless
MCP_API_KEYis 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 |
|
Your own project |
|
Railway |
|
From your own machine | A Cloudflare Tunnel, set up in the console (below). The server, the documents and the index stay where they are |
HTTPS. Put the server behind HTTPS before remote clients connect. OAuth needs an
httpsissuer.One replica. Sessions and pending sign-ins live in memory, and SQLite is one file. Run a single instance.
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 |
|
|
Needs | Nothing | A domain in a Cloudflare account. The console checks the address, then runs |
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 Code, local, without a project |
|
Claude Desktop, Cursor, VS Code, local | The same command and |
Claude Code, remote |
|
Claude and ChatGPT connectors | Console → Connect: your own address, then Sign-in for connectors → Turn on. Add a custom connector with |
Any MCP client | URL |
Upgrading from 0.3
Change | What to do |
Drive scope is | Documents that a trusted owner shared with the service account outside |
zod 4 | Plugins get zod 4 through the exported |
|
|
Google Sheets are read tab by tab | Indexed sheets change on their next modification. Run |
| It searches every source, by keywords with no embedding model. Its permission group is |
Search shows at most 2 passages per document | Set |
Upgrading from 0.2
Change | What to do |
Supabase is optional; SQLite is the default | Existing installs with |
Commands moved into the CLI |
|
Role | Existing rows keep working. |
stdio without | Runs as the local admin instead of refusing to start |
Broken | Now stops the server with the parse error instead of silently using defaults |
Security notes
Never commit
.env, service-account JSON,mcp.config.jsonordata/. All are gitignored and kept out of the image.The data file holds key hashes and OAuth client secrets. It is created owner-only; keep the volume private.
Built-in plugins never change Drive, Slack, GitHub or Railway. The gateway exposes remote write tools only if you set
expose.Drive indexing sends document text to the embedding provider (OpenAI by default; your own server when
EMBEDDING_BASE_URLis 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 inchatgpt-account.jsonin the data directory (owner only), and never sent to the page either.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 thedrivetools: list sensitive folder names indrive.excludeFolders.A token reaches whatever it can read. Scope the Slack bot, the GitHub token and the Railway token to what every user may see.
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
exploreonly one that sees what every permitted person may see. A member without a tool list may use every connection.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 thanlocalhost, 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 plainproxy_pass) looks like a local browser, so on a server leave the console off; and every user of a shared machine can reachlocalhost, where the owner-only token file is what keeps them out.The console token is the admin's key. Its holder can change every setting, and can declare a connection that sends a secret from
.envto 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.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.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 |
Plugin API: | |
Auth, OAuth, permissions, config, gateway, log masking | |
HTTP and stdio transports, MCP request handling, identity | |
Store interface, SQLite and Supabase implementations | |
Built-in plugins: | |
Tools declared in the config: Postgres, SQLite and HTTP connections | |
The console's API, its access rules, and the supervisor that restarts the server after a saved change | |
The console page (React). Built into | |
The command line | |
Unit tests and end-to-end tests over HTTP and stdio | |
The generator and its project template | |
Pack, scaffold, install, build, serve and call, end to end | |
Image, local stack, Railway | |
CI, image and npm workflows, issue and PR templates, README images ( |
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 |
Something behaves differently from the code or the docs | |
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseNot gradedqualityDmaintenanceMCP server for semantic search over Google Drive documents, enabling AI tools to search, list, and retrieve document content.MIT
- AlicenseAqualityBmaintenanceAn 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.3MIT
- AlicenseAqualityCmaintenanceExposes internal databases, HTTP APIs, and files to LLM agents over MCP, with auto-generated schemas, access controls, rate limiting, redaction, and audit logging.3MIT