confluence2md-mcp - MCP Server for confluence2md Indexes

July 9, 2026 · View on GitHub

MCP server that exposes confluence2md-indexer search to any MCP-compatible AI client. Runs as a local stdio server, queries a SQLite index built from confluence2md exports, and returns ranked results with score metadata.

Part of the `confluence2md` Platform

confluence2md-mcp is the third step in a three-tool local Confluence knowledge pipeline. It wraps a SQLite index built by confluence2md-indexer (which indexes output from confluence2md) and serves it to AI clients via MCP. See docs/platform.md for the full architecture.

Requirements

A SQLite index built by confluence2md-indexer
Source content must use confluence2md metadata format — other formats are not supported

Installation

Download the binary for your platform from Releases and place it somewhere on your PATH.

VS Code

Create or edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "confluence2md": {
      "type": "stdio",
      "command": "confluence2md-mcp",
      "args": [],
      "env": {
        "CONFLUENCE_INDEX_DB": "/path/to/confluence2md-index.db"
      }
    }
  }
}

MCP: Add Server in the Command Palette also works.

Claude Code

claude mcp add confluence2md \
  confluence2md-mcp \
  -e CONFLUENCE_INDEX_DB=/path/to/confluence2md-index.db

WSL note: Use the Linux binary, not the Windows .exe — the .exe does not inherit WSL environment variables. The DB path must be a native Linux path (e.g. /home/user/confluence2md-index.db), not /mnt/c/, to avoid SQLite locking issues on NTFS mounts.

Codex CLI

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "confluence2md": {
      "command": "confluence2md-mcp",
      "args": [],
      "env": {
        "CONFLUENCE_INDEX_DB": "/path/to/confluence2md-index.db"
      }
    }
  }
}

Tool

`confluence.search`

Search indexed Confluence content from a local SQLite DB.

Argument	Required	Description
`query`	✓	Search query text
`dbPath`		Override DB path (defaults to `CONFLUENCE_INDEX_DB`)
`mode`		`hybrid` (default) \| `lexical` \| `vector`
`fusion`		`weighted` (default) \| `rrf`
`alpha`		Weighted fusion alpha `[0..1]`, default `0.70`
`rrfK`		RRF k constant, default `60`
`topK`		Candidates to rank, default `10`
`limit`		Max results to return
`offset`		Result offset
`candidateK`		Candidates per retrieval channel, default `50`
`expand`		Context expansion chunk count
`spaceKey`		Filter by space key
`pageId`		Filter by page ID
`fromDate`		Lower bound `YYYY-MM-DD`
`toDate`		Upper bound `YYYY-MM-DD`

Response includes schemaVersion, count, total, and a results array with score breakdown per chunk.

Development

Build

# Linux / macOS / WSL
go build -o bin/confluence2md-mcp .

# Windows
go build -o bin/confluence2md-mcp.exe .

# Cross-compile Linux binary from Windows
GOOS=linux GOARCH=amd64 go build -o bin/confluence2md-mcp-linux-amd64 .

If module downloads fail with 403, set GOPROXY=direct.

Test

go test ./... -run TestMCPStdioSmoke -v

Troubleshooting

No results: verify CONFLUENCE_INDEX_DB points to a built index containing the chunks_fts and embeddings tables.
WSL + Windows binary: use the Linux binary with a native Linux DB path — see the WSL note above.
Tools not appearing in chat: restart your MCP client after registration.