Local Knowledge MCP

A security-first, read-only Model Context Protocol (MCP) server for local folders.

Local Knowledge MCP lets an MCP client browse an explicit root allowlist, inspect metadata, read bounded text, and receive PDF/XLSX files as embedded resources. It is intentionally not a general-purpose filesystem write server.

Features

• Read-only by design and default-deny.

• Client paths use root_alias + relative path; clients never send local absolute paths.

• Blocks unknown roots, parent traversal, symlink escape, hidden paths, and common secret-bearing files.

• Atomically updates the persistent root configuration.

• Reloads the security policy on every tool call, so lk-add, lk-remove, and lk-clear take effect without a project-specific runtime manager.

• Ships as a normal Python package with portable console commands.

• Provides guided ChatGPT setup through OpenAI Secure MCP Tunnel without bundling shared tunnel identities or credentials.

Related MCP server: Document Search MCP Server

Requirements

• Python 3.11 or newer.

• uv is recommended; pipx also works.

• For local stdio usage: an MCP client that can launch a local process.

• For ChatGPT usage: OpenAI tunnel permissions and ChatGPT developer-mode access. lk-chatgpt-setup guides this optional flow.

Install

Directly from GitHub

With uv:

uv tool install "git+https://github.com/TuanLe-bk18/local-knowledge-mcp.git"

Or with pipx:

pipx install "git+https://github.com/TuanLe-bk18/local-knowledge-mcp.git"

From a clone

git clone https://github.com/TuanLe-bk18/local-knowledge-mcp.git
cd local-knowledge-mcp
uv tool install .

The installation provides:

local-knowledge-mcp
lk-init
lk-set
lk-add
lk-list
lk-remove
lk-clear
lk-chatgpt-setup

Quick start

Initialize a secure empty configuration:

lk-init

Add one or more allowed folders:

lk-add project "~/Code/my-project"
lk-add notes "~/Documents/notes"
lk-list

Connect a local stdio MCP client

lk-init prints an MCP client configuration using the installed executable. A typical configuration is:

{
  "mcpServers": {
    "local-knowledge": {
      "command": "local-knowledge-mcp"
    }
  }
}

Some desktop applications do not inherit your shell PATH. In that case, use the absolute command path printed by lk-init.

Restart or reconnect the MCP client after first adding the server. Root allowlist changes made while the server is running are loaded automatically on the next tool call.

See docs/client-setup.md for local stdio setup details and troubleshooting.

Connect ChatGPT with Secure MCP Tunnel

After configuring at least one root, run:

lk-chatgpt-setup

The command:

1. discovers tunnel-client, or offers to download the latest official openai/tunnel-client release;

2. verifies the downloaded archive against the official SHA256SUMS.txt asset;

3. opens OpenAI Platform tunnel and runtime-key setup pages;

4. asks for the user's own tunnel_id and hidden runtime API key;

5. stores the runtime key outside the repository in a user-private 0600 file;

6. starts a managed tunnel runtime and waits until it reports ready;

7. opens ChatGPT connector settings and prints the tunnel ID to select or paste.

The runtime key must have Tunnels Read + Use. An admin key is not accepted, stored, or passed to the long-lived runtime. Tunnel creation remains in the authenticated OpenAI Platform UI, so every installation uses the user's own tunnel identity and permissions.

See docs/chatgpt-setup.md for prerequisites, non-interactive options, credential storage, and troubleshooting.

Root commands

Replace every configured root with one workspace root:

lk-set "/path/to/folder"

Add or update an alias while preserving other roots:

lk-add project "/path/to/project"

List roots without touching the MCP process:

lk-list

Remove one alias:

lk-remove project

Remove all roots while keeping read-only/default-deny policy enabled:

lk-clear

Folder inputs are expanded, required to exist, required to be directories, and saved as canonical absolute paths. Aliases must begin with a lowercase letter and may contain lowercase letters, numbers, hyphens, and underscores.

The persistent configuration is stored outside the repository at:

~/.config/local-knowledge-mcp/security.yaml

No personal root configuration is bundled in the package.

MCP tools

browse(root_alias, path="")
get_info(root_alias, path)
read_text(root_alias, path, max_chars=None)
read_document_resource(root_alias, path)

Example tool arguments:

{
  "root_alias": "project",
  "path": "docs/architecture.md"
}

read_document_resource returns allowed PDF/XLSX files as MCP EmbeddedResource values. It does not parse, OCR, index, or modify documents.

Security model

Every filesystem access reaches SecurityPolicy.resolve() before touching a client-selected path. The default generated policy enforces:

mode:
  read_only: true
  default_deny: true

path_policy:
  allow_absolute_paths_from_client: false
  allow_parent_traversal: false
  allow_symlinks: false
  allow_hidden_files: false

Additional deny patterns block common credential, token, key, environment, build, and VCS paths. Direct text reads are UTF-8 only, extension-limited, binary-checked, file-size limited, and character-limited.

An empty root mapping is valid and denies every root alias. See SECURITY.md before changing policy defaults.

Scope

Included:

• directory browsing;

• file/directory metadata;

• bounded text/source reading;

• PDF/XLSX embedded resources;

• local root allowlist management.

Not included:

• write, edit, delete, move, or create operations;

• arbitrary absolute-path access;

• OCR or document parsing;

• embeddings, vector databases, or RAG;

• a shared hosted tunnel, shared runtime credential, or shared cloud runtime.

For ChatGPT, lk-chatgpt-setup configures the official outbound Secure MCP Tunnel client on the user's machine. This repository never bundles tunnel credentials, identifiers, API keys, or machine-specific runtime state.

Development

git clone https://github.com/TuanLe-bk18/local-knowledge-mcp.git
cd local-knowledge-mcp
uv sync --all-groups
uv run pytest -q
uv build

See CONTRIBUTING.md for contribution guidelines.