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 supported images and documents as MCP content. 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.

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

Update

If installed directly from GitHub with uv, refresh and reinstall the tool from the latest commit:

uv tool upgrade local-knowledge-mcp --reinstall

If installed with pipx:

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

For an installation made from a local clone:

git pull --ff-only origin main
uv tool install --force --reinstall .

Restart or reconnect local MCP clients after upgrading. For a managed ChatGPT tunnel runtime, recreate it with the updated executable:

lk-chatgpt-setup --no-browser

The existing root configuration, tunnel ID, and runtime key file are reused.

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)
read_file_resource(root_alias, path)

Example tool arguments:

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

read_file_resource returns PNG, JPEG, and GIF files as concise text metadata plus MCP ImageContent, with structured output disabled so clients can pass them to a model's image input without duplicating base64 as text. It returns allowed PDF, DOCX, PPTX, XLSX, and XLS files as EmbeddedResource values. It does not parse, OCR, index, or modify files. The existing read_document_resource tool remains available for PDF/XLSX compatibility.

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;
• PNG/JPEG/GIF image content and PDF/DOCX/PPTX/XLSX/XLS 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.