Confluence to Markdown MCP Server

confluence2md-mcp - MCP Server for confluence2md Indexes

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

Environment Variables

Variable	Required	Description
CONFLUENCE_INDEX_DB	recommended	Path to the SQLite DB file. Falls back to confluence2md-index.db in the current working directory if unset.
OPENAI_API_KEY	optional	If set, uses OpenAI embeddings for vector/hybrid search. If unset, falls back to hash embeddings (lower semantic quality, no cost).
OPENAI_EMBED_MODEL	optional	OpenAI embedding model to use. Defaults to text-embedding-3-small. Only used when OPENAI_API_KEY is set.

The embedding provider used at query time must match the one used during indexing. If you indexed with OpenAI embeddings, query with OpenAI; if you indexed with hash fallback, query with hash fallback. Mismatched providers will not cause errors but will produce poor vector search results.

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. Falls back to CONFLUENCE_INDEX_DB env var, then to confluence2md-index.db in the current working directory.
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 fields:

Field	Description
schemaVersion	Schema version string for contract stability
tool	Always "confluence.search"
dbPath	Resolved DB path used for the query
request	Echoed request parameters
count	Number of results returned in this response
total	Total ranked results before pagination
results	Array of result objects with chunk text and score breakdown

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.