docs-mcp
ユーザーが設定したドキュメントを効率的に検索・参照できるMCPサーバーです。
前提条件
docs-mcpを使用するにはuvが必要です。uvはPythonパッケージとプロジェクト管理のための高速なツールです。
uvのインストール
お使いのOSに合わせて選択してください
macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Homebrew (macOS)
brew install uv
pipでのインストール
pip install uv
詳細はuvのインストールガイドを参照してください。
主な機能
- 📄 ドキュメント一覧表示 - すべてのドキュメントとその説明を一覧表示
- 🔍 grep検索 - 正規表現を使った高速な全文検索
- 🧠 セマンティック検索 - OpenAI Embeddingsを使った意味的な類似検索（要設定）
- 📝 ドキュメント取得 - 指定したドキュメントの全内容を取得
- 📖 ページネーション対応 - 大きなドキュメントをページ単位で効率的に閲覧
クイックスタート
🚀 最もシンプルな使い方
既存のドキュメントがあるプロジェクトですぐに使えます：
# ドキュメント管理用フォルダを作成
mkdir -p my-docs/docs
# ドキュメントファイルをdocs/に配置
Claude Desktopの設定（claude_desktop_config.json）に追加：
{
"mcpServers": {
"docs": {
"command": "uvx",
"args": ["docs-mcp"],
"env": {
"DOCS_BASE_DIR": "/path/to/my-docs"
}
}
}
}
重要: docs-mcpは常にプロジェクトフォルダ内のdocs/ディレクトリを参照します。
セットアップガイド
方法1: 既存のドキュメントで使う
手元にあるMarkdownやテキストファイルをすぐに検索可能にできます：
- プロジェクトフォルダを作成
docs/ディレクトリにドキュメントを配置- Claude Desktopの設定を更新
✅ メリット: コマンドライン操作不要、すぐに使える
❌ デメリット: インポートツールが使えない
方法2: インポートツールを活用する
GitHubやWebサイトからドキュメントを取り込む場合：
# ドキュメント管理プロジェクトをセットアップ
uv init my-docs
cd my-docs
uv add docs-mcp
# GitHubからドキュメントをインポート
uv run docs-mcp-import-github https://github.com/owner/repo
# 特定のディレクトリだけインポート
uv run docs-mcp-import-github https://github.com/owner/repo/tree/main/docs -o project-docs
✅ メリット: 外部ドキュメントを簡単に取り込める
❌ デメリット: uvのセットアップが必要
高度な機能
🧠 セマンティック検索を有効にする
OpenAI Embeddingsを使った意味的な検索を追加できます：
# 1. OpenAI APIキーを設定
export OPENAI_API_KEY="sk-..."
# 2. メタデータを生成（プロジェクトディレクトリで実行）
uv run docs-mcp-generate-metadata
Claude Desktopの設定でAPIキーを追加：
{
"mcpServers": {
"docs": {
"command": "uvx",
"args": ["docs-mcp"],
"env": {
"DOCS_BASE_DIR": "/path/to/my-docs",
"OPENAI_API_KEY": "sk-..." // セマンティック検索が有効になる
}
}
}
}
詳細な設定オプション
{
"mcpServers": {
"docs": {
"command": "uvx",
"args": ["docs-mcp"],
"env": {
"DOCS_BASE_DIR": "/path/to/my-docs",
"OPENAI_API_KEY": "sk-...",
"DOCS_FOLDERS": "api,guides,examples", // 特定のフォルダのみ読み込み
"DOCS_FILE_EXTENSIONS": ".md,.mdx,.txt,.py", // 対象ファイル拡張子を制限
"DOCS_MAX_CHARS_PER_PAGE": "5000", // 1ページあたりの最大文字数
"DOCS_LARGE_FILE_THRESHOLD": "10000" // 自動ページネーション閾値（文字数）
}
}
}
}
利用可能なツール
MCPツール（Claude内で使用）
list_docs- ドキュメント一覧表示get_doc- ドキュメント内容取得（ページネーション対応）grep_docs- 正規表現検索semantic_search- 意味的な類似検索（要OpenAI APIキー）
📖 ページネーション機能の使い方
大きなドキュメント（15,000文字超）では自動的に1ページ目が表示され、ページネーションの使用が推奨されます：
# 基本的な使い方（従来通り）
get_doc("path/to/document.md") # 小さなファイルは全文表示、大きなファイルは自動的に1ページ目
# ページネーション使用
get_doc("path/to/document.md", page=1) # 1ページ目（デフォルト10,000文字まで）
get_doc("path/to/document.md", page=2) # 2ページ目
get_doc("path/to/document.md", page=3) # 3ページ目
ページネーション出力例：
📄 Document: pytest/reference/plugin_list.rst
📖 Page 2/5 (chars 10,001-20,000/45,123)
📏 Lines 285-570/1,324 | Max chars per page: 10,000
⚠️ Large document auto-paginated. To see other pages:
💡 get_doc('pytest/reference/plugin_list.rst', page=3) # Next page
💡 get_doc('pytest/reference/plugin_list.rst', page=5) # Last page
────────────────────────────────────────────────────────────
[ドキュメントの内容]
コマンドラインツール（ドキュメント管理用）
docs-mcp-import-url- Webサイトからドキュメントをインポートdocs-mcp-import-github- GitHubリポジトリからインポートdocs-mcp-generate-metadata- セマンティック検索用メタデータを生成
必要な環境
- uv - Python環境とパッケージ管理ツール（
uvxコマンドで実行） - Python 3.12以上（uvが自動的に管理）
- OpenAI APIキー（セマンティック検索を使用する場合のみ）
詳細設定
環境変数
| 変数名 | 説明 | デフォルト値 |
|---|---|---|
OPENAI_API_KEY | OpenAI APIキー（セマンティック検索用） | なし |
DOCS_BASE_DIR | ドキュメントプロジェクトのルート | 現在のディレクトリ |
DOCS_FOLDERS | 読み込むフォルダ（カンマ区切り） | docs/内の全フォルダ |
DOCS_FILE_EXTENSIONS | 対象ファイル拡張子 | デフォルトの拡張子リスト |
DOCS_MAX_CHARS_PER_PAGE | ページネーションの1ページあたりの最大文字数 | 10000 |
DOCS_LARGE_FILE_THRESHOLD | 大きなファイルの自動ページネーション閾値（文字数） | 15000 |
サポートされるファイル形式
クリックして展開
- ドキュメント:
.md,.mdx,.txt,.rst,.asciidoc,.org - 設定:
.json,.yaml,.yml,.toml,.ini,.cfg,.conf,.xml,.csv - コード:
.py,.js,.jsx,.ts,.tsx,.java,.cpp,.c,.h,.go,.rs,.rb,.php - スクリプト:
.sh,.bash,.zsh,.ps1,.bat - Web:
.html,.css,.scss,.vue,.svelte - その他:
.sql,.graphql,.proto,.ipynb,.dockerfile,.gitignore
ディレクトリ構造の例
my-docs/
└── docs/
├── api/
│ └── reference.md
├── guides/
│ └── quickstart.md
└── examples/
└── sample.py
開発者向け情報
ソースからの開発
git clone https://github.com/herring101/docs-mcp.git
cd docs-mcp
uv sync
# テスト
uv run pytest tests/
# ビルド
uv build
コマンドラインツールの詳細
クリックして展開
docs-mcp-import-url
Webサイトからドキュメントをインポート
docs-mcp-import-url https://example.com/docs --output-dir imported
オプション:
--output-dir,-o: 出力ディレクトリ名（docs/配下に保存）--depth,-d: クロール深度--include-pattern,-i: 含めるURLパターン--exclude-pattern,-e: 除外するURLパターン--concurrent,-c: 同時ダウンロード数
docs-mcp-import-github
GitHubリポジトリからインポート。ブランチを指定しない場合はデフォルトブランチ（main/master等）を自動検出します。
# リポジトリ全体をインポート
docs-mcp-import-github https://github.com/owner/repo
# 特定のパスのみインポート（docs/importedに保存される）
docs-mcp-import-github https://github.com/owner/repo/tree/main/docs --output-dir imported
# masterブランチのリポジトリも自動検出
docs-mcp-import-github https://github.com/Cysharp/UniTask
オプション:
--output-dir,-o: 出力ディレクトリ名（docs/配下に保存。デフォルト: リポジトリ名）
docs-mcp-generate-metadata
セマンティック検索用のメタデータを生成
export OPENAI_API_KEY="your-key"
docs-mcp-generate-metadata
セキュリティ
- APIキーは環境変数で管理
DOCS_FOLDERSとDOCS_FILE_EXTENSIONSでアクセスを制限- 外部ネットワークアクセスはOpenAI APIのみ
トラブルシューティング
よくある問題
Claude Desktopに表示されない
- 設定ファイルの構文を確認
DOCS_BASE_DIRが正しいパスを指しているか確認- Claude Desktopを再起動
セマンティック検索が動作しない
OPENAI_API_KEYが設定されているか確認docs-mcp-generate-metadataを実行したか確認
インポートが失敗する
- URL/GitHubリポジトリがアクセス可能か確認
- ネットワーク接続を確認
ライセンス
MIT License - LICENSE
コントリビューション
CONTRIBUTING.mdを参照してください。