zenn-rag
Allows using Google Gemini's embedding API to generate vector representations for indexing Zenn content.
Allows using Ollama's local embedding models to generate vector representations for indexing Zenn content without cloud dependencies.
Allows using OpenAI's embedding API to generate vector representations for indexing Zenn content.
Provides indexing and semantic search over Zenn articles and books, with tools for searching content, getting article details, listing topics, and syncing the index.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
zenn-rag
Zenn 記事・本リポジトリのための Vector DB & RAG(検索・執筆支援)ツールキット。 Markdown記事・チャプターを見出し単位でベクトル化し、CLI検索および Model Context Protocol (MCP) サーバー経由でエディタやAIアシスタント(Cursor、Claude、Antigravityなど)と連携できます。
主な機能
コードブロック保護付き階層チャンキング: Frontmatterメタデータ(タイトル・トピック)と見出し(H1〜H3)の階層構造を保持し、コードブロックを途中で切断せずにベクトル化
Zenn 記事(Articles)& 本(Books)の双方に対応:
articles/*.mdに加え、books/<book-slug>/*.mdの各チャプターも自動認識してインデックス自動同期(ウォッチモード):
index --watchでファイル保存時にバックグラウンドで即時差分同期マルチプロバイダー対応:
OpenAI / LM Studio / LocalAI: 高速バッチEmbedding(
text-embedding-bge-m3,text-embedding-3-smallなど)Google Gemini: レートリミット制御・自動リトライ付き(
gemini-embedding-001)Ollama: ローカルオフライン実行(
bge-m3など)
高速・サーバーレスVector DB: Apache Arrowベースの LanceDB を採用し、コサイン類似度で高精度検索
スマート差分同期: ファイルのMD5ハッシュで変更を検知し、新規・更新された記事・本チャプターのみを数秒で同期
モデル変更の自動検知: モデルや次元数が変わった場合は自動でテーブルをリセット&再構築
MCP サーバー標準搭載:
zenn-rag mcpでAIエディタから過去記事を参照・引用・リンク推薦・インデックス更新が可能
Related MCP server: Snippy MCP Server
インストール
# グローバルインストール
pnpm add -g zenn-rag
# またはプロジェクトに追加
pnpm add -D zenn-ragまたは npx で即座に実行できます:
npx zenn-rag --help設定(.env)
Zenn プロジェクトのルートディレクトリに .env を配置します(.env.example 参照)。
本ツールではプロバイダを切り替えても同じ環境変数名(BASE_URL, EMBEDDING_MODEL, API_KEY)で直感的に設定できます。
共通環境変数一覧
環境変数名 | 必須 | デフォルト値 | 説明 |
| 任意 |
| 使用するプロバイダ ( |
| 任意 | プロバイダ依存 | エンドポイントURL(LM Studio や Ollama 利用時に指定) |
| 任意 | プロバイダ依存 | 使用する埋め込みモデル名 |
| 条件付 | - | APIキー(Gemini, OpenAI利用時に必須。LM Studio等は任意文字列で可) |
| 任意 | - | 記事・本のURL生成用ユーザー名(指定時は |
| 任意 |
| Vector DB (LanceDB) のデータ保存ディレクトリ |
⚠️ 注意: 生成される
.vectordbディレクトリはローカルのバイナリデータベースです。Git で管理しないよう、Zenn リポジトリの.gitignoreに追加してください:.vectordb
💡 Tip: 従来の
OPENAI_BASE_URLやGEMINI_API_KEY,OLLAMA_EMBEDDING_MODELなどのプロバイダ別環境変数もそのまま利用可能です(個別設定がある場合はそちらが優先されます)。
代表的なプロバイダ設定例
1. LM Studio(OpenAI 互換ローカルサーバー / 推奨)
完全ローカルで高速・無料にベクトル化できます。
EMBEDDING_PROVIDER=openai
BASE_URL=http://localhost:1234/v1
EMBEDDING_MODEL=text-embedding-bge-m3
API_KEY=lm-studio
ZENN_USERNAME=your_zenn_id
VECTOR_DB_DIR=.vectordb2. Ollama(完全ローカル・オフライン)
EMBEDDING_PROVIDER=ollama
BASE_URL=http://localhost:11434
EMBEDDING_MODEL=bge-m3
ZENN_USERNAME=your_zenn_id
VECTOR_DB_DIR=.vectordb3. Google Gemini(クラウド)
Google AI Studio で取得した無料〜従量課金の API キーを使用します。
EMBEDDING_PROVIDER=gemini
API_KEY=AIzaSy...
EMBEDDING_MODEL=gemini-embedding-001
ZENN_USERNAME=your_zenn_id4. OpenAI API(クラウド)
EMBEDDING_PROVIDER=openai
API_KEY=sk-...
EMBEDDING_MODEL=text-embedding-3-small
ZENN_USERNAME=your_zenn_idコマンド一覧
1. インデックス同期(差分更新・自動同期)
# 変更・新規コンテンツのみ差分同期
npx zenn-rag index
# ファイルを監視し、保存時に自動で差分同期(ウォッチモード)
npx zenn-rag index --watch
# 全記事・本を強制再同期
npx zenn-rag index --force
# 対象ディレクトリを指定する場合
npx zenn-rag index --dir /path/to/zenn-repo2. 過去記事・本の検索(CLI)
# 基本検索
npx zenn-rag search "Cloudflare Workers WASM"
# 取得件数とトピック絞り込み
npx zenn-rag search "App Router キャッシュ" --limit 3 --topic nextjs3. 進捗・トピック統計の確認
npx zenn-rag status4. MCPサーバー起動
npx zenn-rag mcpおすすめ npm scripts 設定
Zenn プロジェクトの package.json に以下を登録しておくと、日々の執筆や検索を短いコマンドで手軽に実行できます:
{
"scripts": {
"rag:sync": "zenn-rag index",
"rag:watch": "zenn-rag index --watch",
"rag:status": "zenn-rag status",
"rag:search": "zenn-rag search",
"rag:mcp": "zenn-rag mcp"
}
}よく使う実行例
# 執筆中に裏で自動同期(保存時に即時差分更新されるため推奨)
pnpm run rag:watch
# 過去記事・本を検索(引数を渡して実行)
pnpm run rag:search "Cloudflare Workers WASM"
# 現在のインデックス進捗・トピック集計を確認
pnpm run rag:statusMCP(AIエディタ連携)設定
Antigravity、Claude Desktop、Cursor などの MCP 設定ファイル(mcpServers)に本設定を追加します。
Claude Desktop:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Cursor:
プロジェクトルートの
.cursor/mcp.jsonまたは
Cursor Settings>Features>MCP>Add new MCP server
Antigravity:
設定メニューの MCP 項目または
mcp_config.json
macOS / Linux の場合
{
"mcpServers": {
"zenn-rag": {
"command": "npx",
"args": ["-y", "zenn-rag", "mcp"],
"cwd": "/Users/username/path/to/zenn-repo"
}
}
}Windows の場合
Windows では cwd のパス区切りに スラッシュ / または 二重エスケープ \\ を使用します:
{
"mcpServers": {
"zenn-rag": {
"command": "npx",
"args": ["-y", "zenn-rag", "mcp"],
"cwd": "C:/prog/zenn-repo"
}
}
}💡 Windows での注意点:
パスの書き方: JSON 内では
"C:/prog/zenn-repo"(スラッシュ推奨)または"C:\\prog\\zenn-repo"(バックスラッシュ2重)で指定してください。単体の\は JSON パースエラーになります。
npxが見つからない場合: 一部のエディタ(Claude Desktop 等)でnpx実行時にENOENTエラーが出る場合は、以下のようにcmd.exe経由で実行してください:"command": "cmd.exe", "args": ["/c", "npx", "-y", "zenn-rag", "mcp"]
提供ツール
search_articles: 自然言語でクエリに類似する過去記事・本チャプターのセクション・スコア・URLを検索suggest_related_links: 執筆中の文章やメモから、引用・内部リンクすべき関連記事や本をMarkdownリンク形式で推薦get_article: スラッグを指定して記事・チャプター全体の構成や内容を取得list_topics: 蓄積されたコンテンツの全トピックと件数を集計sync_index: AIエディタ内から直接インデックスの差分更新を実行
ライブラリとしての利用
import {
searchArticles,
syncIndex,
ArticleVectorStore,
initContext,
} from "zenn-rag";
// コンテキストの初期化
initContext("/path/to/zenn-repo");
// 検索実行
const results = await searchArticles("React Server Actions", { limit: 3 });
console.log(results);開発
# 依存パッケージのインストール
pnpm install
# ビルド(TypeScript 公式コンパイラ tsc で dist/ に出力)
pnpm run build
# テスト実行
pnpm test
# ウォッチモード(ビルド / テスト)
pnpm run dev
pnpm run test:watchライセンス
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
Search and manage your team's knowledge from MCP clients.
MCP-native collaborative markdown editor with real-time AI document editing
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server for a content-first knowledge base, enabling AI agents to search (full-text, semantic, hybrid) and retrieve Markdown documents, list content, and find related docs.9 npmMIT
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to save and retrieve code snippets, perform semantic vector search, generate code style guides and wiki documentation, and orchestrate multi-agent workflows through MCP tools.-
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to save and retrieve code snippets, generate language-specific style guides, create wiki documentation, and orchestrate multi-agent documentation workflows through MCP tools backed by vector search.-
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to search, read, create, edit, archive, and comment on documents; manage collections; find backlinks; and access content through MCP resources.-