Docs MCP

A server for efficiently searching and referencing user-configured local documents.

View on GitHub →

docs-mcp

Test License: MIT

ユーザーが設定したドキュメントを効率的に検索・参照できるMCPサーバーです。

前提条件

docs-mcpを使用するにはuvが必要です。uvはPythonパッケージとプロジェクト管理のための高速なツールです。

uvのインストール

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やテキストファイルをすぐに検索可能にできます：

  1. プロジェクトフォルダを作成
  2. docs/ディレクトリにドキュメントを配置
  3. 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_KEYOpenAI 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を参照してください。

Related Servers