快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

命令预览

docker run --rm -i martoc/mcp-clickhouse-documentation:latest

详细介绍

MCP ClickHouse文档服务器

模型上下文协议（MCP）服务器，使Claude能够搜索和阅读ClickHouse官方文档。采用FastMCP和SQLite FTS5构建，可实现BM25排名的高效全文搜索。

特性

全文搜索 跨ClickHouse文档和知识库
MDX解析 -使用JSX组件处理Docusaurus MDX文件
BM25排名 -相关性排名搜索结果
分段过滤 -在特定文档部分搜索
多目录索引 -涵盖两者 docs/ 和 knowledgebase/
快速MCP集成 -准备好使用克劳德桌面和克劳德代码

快速开始

安装

# Clone repository
git clone https://github.com/martoc/mcp-clickhouse-documentation.git
cd mcp-clickhouse-documentation

# Initialise development environment
make init

# Index ClickHouse documentation
make index

MCP配置

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "clickhouse-documentation": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-clickhouse-documentation",
        "run",
        "mcp-clickhouse-documentation"
      ]
    }
  }
}

Docker容器

运行带有索引文档的预构建容器：

# Pull the image
docker pull martoc/mcp-clickhouse-documentation:latest

# Run the server
docker run --rm -i martoc/mcp-clickhouse-documentation:latest

Docker的MCP配置：

{
  "mcpServers": {
    "clickhouse-documentation": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "martoc/mcp-clickhouse-documentation:latest"
      ]
    }
  }
}

可用标签：

latest -具有预索引文档的最新稳定版本
v0.3.0 -特定版本发布
main -主分支机构的最新提交

用法

配置后，Claude可以：

搜索文档：

- “在ClickHouse文档中搜索SELECT语句” - “查找有关Kafka集成的信息” - “如何使用ARRAY函数？”

阅读完整文档：

- “阅读完整的SELECT引用” - “给我看完整的Kafka集成指南”

工具

MCP服务器提供两个工具：

`search_documentation`

使用全文搜索搜索ClickHouse文档。

参数：

query （必填）：搜索查询
section （可选）：按部分筛选（例如，“sql引用”、“知识库集成”）
limit （可选）：最大结果（默认值：10）

退货：

title：文档标题
url：完整文档URL
path：相对文件路径
section：文件部分
snippet：突出显示匹配项的内容片段
relevance_score：BM25相关性得分

`read_documentation`

阅读文档页面的完整内容。

参数：

path （必填）：搜索结果中的文档路径

退货：

path：文档路径
title：文档标题
description：文档描述
section：文件部分
url：完整文档URL
content：完整的文档内容（清理过的MDX/Markdown）

建筑

mcp-clickhouse-documentation/
├── src/mcp_clickhouse_documentation/
│   ├── models.py          # Data models
│   ├── parser.py          # MDX/Markdown parser
│   ├── database.py        # SQLite FTS5 operations
│   ├── indexer.py         # Documentation indexer
│   ├── server.py          # FastMCP server
│   └── cli.py             # Command-line interface
├── tests/                 # Test suite
├── Makefile               # Build automation
└── pyproject.toml         # Project configuration

发展

先决条件

Python 3.12+
uv包管理器
Git

命令

# Initialise environment
make init

# Run tests
make test

# Run linting and type checking
make build

# Format code
make format

# Index documentation
make index

# View statistics
make stats

# Run MCP server
make run

# Clean artifacts
make clean

测试

# Run all tests with coverage
make test

# Run specific test file
uv run pytest tests/test_parser.py -v

# Run with coverage report
uv run pytest --cov=src/mcp_clickhouse_documentation --cov-report=html

技术细节

MDX解析

解析器通过以下方式处理Docusaurus MDX文件：

提取YAML前体（标题、描述）
删除JSX导入和导出
剥离JSX组件和表达式
清理HTML标签和注释
保留Markdown格式

数据库模式

带FTS5虚拟表的SQLite：

主表： documents -存储完整的文档数据
FTS表： documents_fts -全文搜索索引
BM25排名： 标题（5.0）、描述（2.0）、内容（1.0）
触发器： 表之间的自动同步

存储库索引

稀疏结账： 只有克隆 docs/ 和 knowledgebase/ 目录
浅层克隆： 用途 --depth 1 更快的克隆
文件类型： 索引两者 .md 和 .mdx 文件
URL模式： 匹配ClickHouse文档的干净URL（无扩展名）

统计

索引后，查看统计信息：

make stats

输出示例：

ClickHouse Documentation Index Statistics
==================================================
Total documents: 856

Documents by section:
--------------------------------------------------
  sql-reference                   324 ( 37.9%)
  operations                      156 ( 18.2%)
  knowledgebase-integrations      128 ( 15.0%)
  engines                          98 ( 11.4%)
  interfaces                       87 ( 10.2%)
  development                      63 (  7.4%)
==================================================

Docker部署

塑造形象

Docker镜像包括一个预先索引的文档数据库，可供立即使用：

# Build multi-platform image
make docker-build

# Or manually
docker build -t martoc/mcp-clickhouse-documentation:latest .

多阶段构建过程：

建设者阶段 -安装依赖项、克隆文档和索引文档
运行阶段 -复制索引数据库并运行MCP服务器

发布到容器注册表

# Tag with version
docker tag martoc/mcp-clickhouse-documentation:latest \
  martoc/mcp-clickhouse-documentation:v0.3.0

# Push to Docker Hub
docker push martoc/mcp-clickhouse-documentation:latest
docker push martoc/mcp-clickhouse-documentation:v0.3.0

集装箱特征

✅ 预索引数据库 -立即准备使用
✅ 多架构 -支持AMD64和ARM64
✅ 优化图层 -高效缓存和最小大小
✅ 片段过滤 -无错误的干净索引
✅ 快速启动 -包含数据库，无需索引

图像大小

压缩的：~50-70 MB
未压缩：~150-200MB
包含：Python运行时、依赖关系和索引文档

故障排除

找不到数据库

# Re-index documentation
make index --force

搜索未返回任何结果

# Check database statistics
make stats

# Verify database exists
ls -lh ~/.cache/mcp-clickhouse-documentation/

分析器错误

检查日志中的特定文件解析错误：

# Run indexer with verbose logging
uv run clickhouse-docs-index index

贡献

克隆该仓库
创建要素分支
进行更改
运行测试： make build
提交拉取请求

许可证

MIT许可证-详见许可证文件。

另见

目录标签

全文搜索PythonClaude本地部署文档解析ClickHouse支持BM25排序MDX处理

支持客户端

Claude DesktopClaude

接入字段

传输方式（transport，传输协议）

stdio

鉴权方式（authType，认证方式）

none

运行时（runtime，运行环境）

Docker

工具数量（toolCount，工具数）

2

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

stdionone部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

来源信息

MCP World

mcpworld.com

/detail/b1cbfb8caa547aa7edb514d06fe49beb

一个基于FastMCP和SQLite FTS5的ClickHouse文档全文搜索服务，支持BM25排序和MDX解析。

继续浏览同类 MCP

更多搜索检索 MCP（7,303）返回 MCP 目录

上一个 MCP

MCP Claude Spotify

An integration that allows Claude Desktop to interact with Spotify using the Model Context Protocol (MCP).

下一个 MCP

MCP Client Agent Airbnb

一个结合Airbnb搜索功能和OpenAI向量存储持久化记忆的多服务器模型上下文协议(MCP)客户端。

MCP Clickhouse Documentation