mcp-wiki-helper-tools

MCP server for querying a Wiki stored in a Git repository.

It syncs the Wiki, indexes the Markdown files, and provides tools to list, search, and read documents in Codex or VS Code.

Features

Related MCP server: py-mcp-wiki-helper

How it works

1. The MCP clones or updates the Wiki's Git repository.

2. Finds all .md files.

3. Creates an in-memory index.

4. Makes the tools available through the HTTP /mcp route.

5. Updates the Wiki periodically.

The folder defined in WIKI_LOCAL_PATH is updated with git reset --hard. Do not make manual changes to it, as they will be discarded.

1. Set up the server

On the machine where the MCP will run, enter the project folder:

cd "/caminho/para/mcp-wiki-helper"

Install the dependencies:

npm install

Create the .env file:

cp .env.example .env

Fill in the .env:

WIKI_REPOSITORY_URL=git@github.com:empresa/wiki.git
WIKI_LOCAL_PATH=./data/wiki
WIKI_BRANCH=main
WIKI_SYNC_INTERVAL_MS=1800000

MCP_HTTP_HOST=0.0.0.0
MCP_HTTP_PORT=3000
MCP_HTTP_ROUTE=/mcp

To make the first test easier on the local network, do not configure MCP_API_KEY.

2. Start the server

Compile:

npm run build

Start:

npm run start:http

Keep that terminal open. The expected message is:

[MCP] HTTP ativo em http://0.0.0.0:3000/mcp

Find out the machine's IP:

hostname -I

If necessary, open the port on the local network:

sudo ufw allow from 192.168.0.0/16 to any port 3000 proto tcp

3. Test the connection

On the other machine, run:

curl http://IP_DO_SERVIDOR:3000/health

Example:

curl http://192.168.3.233:3000/health

Expected response:

{
  "status": "ok",
  "documents": 100
}

The documents field must be greater than zero.

4. Connect in Codex

In Codex:

1. Open Settings.

2. Go to MCP servers.

3. Click + Add server.

4. Choose the URL/HTTP type.

5. Use the name wiki-helper.

6. Fill in only the URL:

http://IP_DO_SERVIDOR:3000/mcp

Example:

http://192.168.3.233:3000/mcp

Leave these fields completely empty:

• Bearer token env var

• Headers

• Headers from environment variables

Do not write none in the authentication fields.

Then:

1. Save the server.

2. Turn on the toggle next to wiki-helper.

3. Open a new conversation in Codex.

4. Send:

Use list_documents do MCP wiki-helper e mostre os primeiros 10 documentos.

If Codex reports that the none environment variable does not exist:

1. Open Settings > MCP servers > wiki-helper.

2. Click Uninstall.

3. Add it again filling in only the URL.

4. Leave all authentication fields empty.

5. Connect in VS Code/Copilot

In VS Code:

1. Press Ctrl+Shift+P.

2. Run MCP: Open User Configuration.

3. Put it in the mcp.json file:

{
  "servers": {
    "wiki-helper": {
      "type": "http",
      "url": "http://IP_DO_SERVIDOR:3000/mcp"
    }
  }
}

Then run MCP: List Servers, select wiki-helper, and choose Start Server.

6. Usage examples

Check the server:

Use a ferramenta Server do MCP wiki-helper.

List documents:

Use list_documents do wiki-helper e mostre os primeiros 10 documentos.

Search by name:

Use search_documents do wiki-helper para procurar "autenticação".

Search within the Wiki:

Use search_content do wiki-helper para pesquisar "JWT", com limite 5.

Read a document:

Use read_document do wiki-helper para ler "caminho/documento.md" e faça um resumo.

Common issues

ECONNREFUSED ...:80 error

The URL is missing the port or the route. Always use:

http://IP_DO_SERVIDOR:3000/mcp

The /authorize route opened

The client tried to use OAuth. This MCP does not have OAuth. Remove the authentication and leave the Bearer and Headers fields empty.

The MCP does not connect

Check on the server machine:

npm run start:http
ss -lntp | grep 3000

Test again on the client machine:

curl http://IP_DO_SERVIDOR:3000/health

The Wiki does not return documents

Check whether the configured folder contains Markdown files:

find ./data/wiki -type f -name '*.md' | head

Also check access to the Git repository configured in WIKI_REPOSITORY_URL.

Security

• Use this unauthenticated mode only on a controlled local network.

• Do not expose port 3000 directly to the internet.

• For external access, use HTTPS, authentication, and a reverse proxy.

• Never commit keys or credentials in .env.