MCP Code Checker

MCP Tools Py

簡単なクライアント設定でコード品質チェックを実行できる、Model Context Protocol（MCP）サーバーです。このサーバーは、MCP プロトコルの設計に従って、指定したプロジェクトディレクトリ内でコード品質チェックを実行するための API を提供します。

概要

この MCP サーバーを使用すると、Claude Desktop 経由の Claude、GitHub Copilot を利用する VSCode、その他の MCP 互換クライアントなどの AI アシスタントが、Python プロジェクトでコード品質チェック、フォーマット、リファクタリングを実行できます。全ツールの一覧については、利用可能なツールをご覧ください。

対象範囲： このサーバーの対象は Python プロジェクトのみです。同様の機能を持つ専用の MCP サーバーを別途用意することで、他の言語にも対応できます。

bash アクセスではなく専用の MCP サーバーを使う理由

汎用の bash MCP ツールは柔軟性が高い一方、制御性は低くなります。このサーバーは、より対象を絞ったアプローチを採用しています。

• セキュリティ：実行できるのは定義済みのツールのみです。利用可能なツールをご覧ください。すべての操作は、指定された project_dir の範囲内で実行されます。
• コンテキスト管理：結果は AI アシスタントのコンテキスト負荷を軽減するために、形式を整え、サイズを制限して出力されます。出力はツールの生の結果ではなく、実行可能なプロンプトとして構造化されています。
• 透明性：このサーバーはオープンソースであり、詳細な構造化ログに、各ツール呼び出しのパラメーター、所要時間、結果が記録されます。

機能

すべてのツールは利用可能なツールに記載されています。以下のセクションでは、最もよく使われるツールのパラメーターについて説明します。

Pylint のパラメーター

pylint ツールでは、次のパラメーターを指定してカスタマイズできます。

パラメーター	型	デフォルト	説明
extra_args	list	None	追加の pylint CLI 引数を指定する任意のリストです（例：["--disable=W0611"]）
target_directories	list	None（自動検出）	project_dir からの相対パスで指定する解析対象ディレクトリです。省略した場合は pyproject.toml から自動検出されます
max_issues	integer	1	詳細に表示する問題の種類の数です。残りは件数のみ要約されます。0 = 件数のみ（ルールごとの件数とディレクトリ別の内訳）

Pylint の設定

Pylint はプロジェクトの pyproject.toml を自動的に読み込みます。pyproject.toml の [tool.pylint.messages_control] を設定して、報告する問題を指定してください。例と移行に関するガイダンスについては、docs/pyproject-configuration.mdをご覧ください。

対象ディレクトリの自動検出

target_directories が指定されていない場合、このパラメーターを受け付けるツール（pylint、mypy、ruff check、ruff fix、bandit、vulture、run_format_code）は、pyproject.toml からディレクトリを自動検出します。

• ソースディレクトリ：[tool.setuptools.packages.find] where から検出します（フォールバック：["src"]）
• テストディレクトリ：[tool.pytest.ini_options] testpaths から検出します（フォールバック：["tests"]）

run_deptry_check はテストパスを除外し、ソースディレクトリのみを自動検出します。

ディスク上に存在するディレクトリのみが含まれます。リストを明示的に渡すことで、自動検出を上書きできます。

• ["src"] - ソースコードディレクトリのみを解析します
• ["src", "tests"] - ソースディレクトリとテストディレクトリの両方を解析します
• ["mypackage", "tests"] - パッケージ構成が異なるプロジェクト向けです
• ["."] - プロジェクトディレクトリ全体を解析します（大規模なプロジェクトでは時間がかかる場合があります）

Pytest のパラメーター

run_pytest_check では、カスタマイズ用に次のパラメーターを使用できます。

パラメーター	型	デフォルト	説明
markers	list	None	テストを絞り込むための任意の pytest マーカーのリスト
extra_args	list	None	追加の pytest 引数の任意のリスト。詳細度を制御するには -v／-vv／-vvv を使用します
env_vars	dictionary	None	サブプロセスに渡す任意の環境変数
timeout_seconds	integer	None（設定から解決され、設定がない場合は 300）	テストの実行を待つ最大秒数。正の整数のみ指定できます
coverage	boolean	False	pytest-cov でカバレッジを測定し、返信にカバレッジの要約を追加します
coverage_source	list	None（自動検出）	測定対象のディレクトリ。[tool.setuptools.packages.find] where からテストパスを除外して自動検出されます
max_modules	integer	10	カバレッジの要約で各リストに詳細を表示するモジュール数

注： デフォルトで pytest-xdist を使用した並列テスト実行（-n auto）が有効になっています。

カバレッジ： coverage=True を使用するには、プロジェクトの環境に pytest-cov がインストールされている必要があります。要約には、合計値、未実行のステートメントが最も多いモジュールと関数ごとの行範囲、カバレッジがないモジュール、および集計対象となったテストの選択範囲が表示されます。プロジェクトの fail_under は報告されますが適用されないため、合否はテストのみで決まります。コードを除外するには、coverage 独自の [tool.coverage.run] omit または # pragma: no cover を使用します。

Mypy のパラメーター

mypy ツールでは、カスタマイズ用に次のパラメーターを使用できます。

パラメーター	型	デフォルト	説明
disable_error_codes	list	None	無視する mypy エラーコードのリスト
target_directories	list	None（自動検出）	project_dir からの相対パスで指定するチェック対象ディレクトリ。省略すると pyproject.toml から自動検出されます
follow_imports	string	None（フラグは渡されず、プロジェクトの [tool.mypy] で決まります）	型チェック中のインポートの処理方法
cache_dir	string	None（フラグは渡されず、MYPY_CACHE_DIR、次に [tool.mypy] cache_dir、それらがない場合は .mypy_cache で決まります）	インクリメンタルチェック用のカスタムキャッシュディレクトリ
timeout_seconds	integer	None（設定から解決され、設定がない場合は 120）	mypy の実行を待つ最大秒数。正の整数のみ指定できます
max_issues	integer	None	詳細を表示するエラーコード数（それぞれ最大 5 か所）。残りのコードはそれぞれ要約の 1 行で表示されます。None の場合はすべてのコードの詳細を表示し、0 の場合は件数のみ（コードごとの件数とディレクトリ別の内訳）を表示します

Mypy の設定

mypy はプロジェクトの pyproject.toml を自動的に読み込み、フラグの設定は [tool.mypy] を唯一の情報源とします。follow_imports、cache_dir、disable_error_codes を渡さない限り、ツールが追加するのは出力形式のフラグのみです。独自の [tool.mypy] セクションがないプロジェクトには最低限の設定もありません。適用される設定がない場合、mypy のデフォルト設定で実行され、ほとんどチェックしていなくても「passed」と報告します。一方、親ディレクトリの設定（mypy 1.15 以降）、または適用範囲内のユーザーレベルの ~/.config/mypy/config や ~/.mypy.ini がある場合は、その設定で実行され、プロジェクトが求めていないエラーを報告することがあります。移行のガイダンスと mypy のキャッシュへの影響については、docs/pyproject-configuration.md を参照してください。

コマンドラインインターフェイス（CLI）

基本的な使い方

mcp-tools-py --project-dir /path/to/project [options]

必須パラメーター

パラメーター	型	説明
--project-dir	string	必須。コードチェック操作の基準ディレクトリ

オプションのパラメーター

Python の設定

パラメーター	型	デフォルト	説明
--python-executable	string	sys.executable	プロジェクトの環境にある Python インタープリターのパスです。pytest、pylint、mypy、deptry はこの環境で実行され、ライブラリやシンボルの検索もこの環境を対象とするため、プロジェクトの依存関係がインストールされ、deptry もインストールされている環境を指定する必要があります。black、isort、ruff、bandit、vulture、tach、lint-imports は mcp-tools-py 自身の環境から実行されるため、この環境にインストールする必要はありません。単純な名前を指定した場合は PATH から検索されます。存在しないパス、または解決できないパスを指定すると、起動時に失敗します
--venv-path	string	None	非推奨で、--help には表示されません。引き続き受け付けられ、引き続きインタープリターの解決に使われます（--python-executable より優先されます）が、ツールの場所の特定には使われなくなりました。代わりに --python-executable を使用してください

テストの設定

パラメーター	型	デフォルト	説明
--test-folder	string	"tests"	テストフォルダーへのパス（project-dir からの相対パス）
--keep-temp-files	flag	False	テスト実行後も一時ファイルを保持します。テストが失敗した場合のデバッグに役立ちます

ログの設定

パラメーター	型	デフォルト	説明
--log-level	string	"INFO"	ログレベルを設定します。選択肢：DEBUG、INFO、WARNING、ERROR、CRITICAL
--log-file	string	None	構造化 JSON ログの保存先パスです。指定しない場合、ログは project_dir/logs/mcp_tools_py_{timestamp}.log に出力されます
--console-only	flag	False	コンソールのみにログを出力します。デフォルトのログファイルは作成されず、--log-file は無視されます

ツールの設定

パラメーター	型	デフォルト	説明
--check-timeout	integer	None (120; pytest 300)	各チェッカーおよびフォーマッターのサブプロセスに対するタイムアウト（秒）です。プロジェクトの pyproject.toml にある [tool.mcp-tools-py] でツールごとに上書きできます。詳しくはプロジェクトの設定を参照してください
--refactoring-timeout	integer	120	rope のリファクタリング処理に対するタイムアウト（秒）です
--vulture-whitelist	string	"vulture_whitelist.py"	vulture のホワイトリストファイルへのパスです（project-dir からの相対パス）。ファイルが存在する場合、run_vulture_check によって自動的に含められます

注記

• 非推奨の --venv-path を指定すると、--python-executable より優先されます。現在はインタープリターの解決だけに使われます
• --console-only フラグは、ログファイルの作成を避けたい開発時に便利です
• ログファイルは、構造化された分析ができるよう JSON 形式で作成されます
• --keep-temp-files を指定しない限り、一時ファイルは自動的に削除されます

環境設定

使用する環境は2つあり、設定できるのはそのうち1つだけです。

• プロジェクト環境 — --python-executable で指定します。プロジェクトの依存関係と、それらをインポートまたは調査して動作する pytest、pylint、mypy、deptry が含まれます。ライブラリとシンボルの解決（get_library_source、list_symbols、find_references）も同じインタープリターに従うため、このフラグに誤った仮想環境を指定すると、これらのツールは誤ったパッケージを対象に解決します。
• ツール環境 — mcp_tools_py 自体がインストールされている環境です。mcp-tools-py 自身の依存関係である black、isort、ruff、bandit、vulture、tach、lint-imports が含まれます。設定できません。

そのため、これら7つのツールはツール環境にインストールされているバージョンで実行されます。プロジェクトで指定しているバージョンと異なる場合があるため、CI との整合性を保ちたいプロジェクトでは、両方の環境で互換性のある範囲を維持してください。lint-imports は引き続き作業ツリーをチェックします。ツール環境から実行されますが、import-linter の設定から読み取ったプロジェクトのルートパッケージを、プロジェクトのインタープリターを通じて特定します。そのルートパッケージ内にあるカスタムの contract_types エントリーも、同じブリッジを通じて解決されます。一方、プロジェクト環境にのみインストールされた別のディストリビューション内にあるエントリーは解決されません。渡されるのはルートパッケージのディレクトリだけだからです。

以下の最初の例では、環境変数を埋め込んでこのパスを作成します。そのため、環境変数が未設定または古い値のままだと、--python-executable の指定先が存在しないパスになります。その場合、サーバーは起動時にフラグ名を示す FileNotFoundError を発生させ、起動後にプロジェクトのツールが見つからないと報告することはありません。python3 のようなインタープリター名をそのまま指定すると、代わりに PATH から検索されます。

正しい設定

プロジェクトの仮想環境を指定してください。Windows では、pytest、pylint、mypy がインストールされた環境を次のように指定します。

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": [
                "--project-dir", "/path/to/your/project",
                "--python-executable", "${VIRTUAL_ENV}\\Scripts\\python.exe"
            ]
        }
    }
}

macOS と Linux では、インタープリターは代わりに bin 内にあります。

                "--python-executable", "${VIRTUAL_ENV}/bin/python"

誤った設定

プロジェクトのものではないインタープリターを指定しないでください。

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": [
                "--project-dir", "/path/to/your/project",
                "--python-executable", "/usr/bin/python3"
            ]
        }
    }
}

システムのインタープリター、またはプロジェクトのものではない仮想環境を指定すると、pytest、pylint、mypy が見つからないと報告され、ライブラリやシンボルの検索も誤ったパッケージを対象に行われます。プロジェクト自身の .venv も、この3つがインストールされていない場合は同じように失敗します。その場合はフラグの指定先を変えるのではなく、その環境にインストールしてください。

トラブルシューティング

• 起動時に 「Python interpreter not found」 と表示される場合：--python-executable が存在しないパスを指定しています。通常は、パスに埋め込まれている環境変数が未設定であることが原因です。メッセージには、パスの指定に使われたフラグが示されます。
• 「No module named pytest」（または pylint/mypy）と表示される場合：--python-executable が、必要なツールがインストールされていない環境を指定しています。プロジェクトの環境を指定し、その環境にツールをインストールしてください。
• 「ruff is not available」（または black/isort/bandit/vulture/tach/lint-imports）と表示される場合：これらのコンソールスクリプトは --python-executable ではなくツール環境から提供されるため、フラグは原因ではありません。mcp-tools-py の依存関係であるため、メッセージに示された検索対象のツール環境ディレクトリを確認し、依存関係を含めて mcp-tools-py を再インストールしてから、サーバーを再起動してください。
• 不足していたツールをインストールした後：pytest、pylint、mypy の確認には、設定されたインタープリターを調べるプローブが使われます。このプローブは1回だけ実行され、プロセスの終了までキャッシュされるため、この3つのうちいずれかをインストールした後は MCP サーバーを再起動してください。

インストール

詳しいインストール手順については、INSTALL.md を参照してください。

クイックインストール：

# Install from GitHub (recommended)
pip install git+https://github.com/MarcusJellinghaus/mcp-tools-py.git

# Verify installation
mcp-tools-py --help

開発用インストール：

# Clone and install for development
git clone https://github.com/MarcusJellinghaus/mcp-tools-py.git
cd mcp-tools-py
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
mcp-tools-py --help

MCP クライアントの設定

このサーバーは、別途インストールする Python ツールの mcp-config を使って設定できます。このツールは、このパッケージの依存関係ではありません。次の機能を提供します。

• 対話型セットアップ：Claude Desktop および VSCode に対応しています
• 設定管理：サーバー設定の追加、削除、表示ができます
• サーバーリポジトリ：厳選された MCP サーバーコレクションにアクセスできます

前提条件： Python をインストールしてから、mcp-config を別途インストールしてください。

注： Windsurf や Cursor など、ほかの MCP クライアントも MCP サーバーに対応していますが、手動での設定が必要な場合があります。

依存関係として使用する

requirements.txt の場合

requirements.txt に次の行を追加します。

mcp-tools-py @ git+https://github.com/MarcusJellinghaus/mcp-tools-py.git

pyproject.toml の場合

プロジェクトの依存関係に追加します。

[project]
dependencies = [
    "mcp-tools-py @ git+https://github.com/MarcusJellinghaus/mcp-tools-py.git",
    # ... other dependencies
]

# Or as an optional dependency
[project.optional-dependencies]
dev = [
    "mcp-tools-py @ git+https://github.com/MarcusJellinghaus/mcp-tools-py.git",
]

インストールコマンド

requirements.txt または pyproject.toml に追加した後、次を実行します。

# Install from requirements.txt
pip install -r requirements.txt

# Install from pyproject.toml
pip install .
# Or with optional dependencies
pip install ".[dev]"

サーバーを実行する

CLI コマンドを使用する（推奨）

インストール後、mcp-tools-py コマンドを使ってサーバーを実行できます。

mcp-tools-py --project-dir /path/to/project [options]

Python モジュールを使用する（代替方法）

Python モジュールとしてサーバーを実行することもできます。

python -m mcp_tools_py --project-dir /path/to/project [options]

# Or for development (from source directory)
python -m src.main --project-dir /path/to/project [options]

使用可能なコマンドラインオプションの詳細については、CLI のセクションを参照してください。

プロジェクト構成への対応

サーバーは、標準的なプロジェクト構成にある Python コードを自動的に検出して解析します。

デフォルトの解析対象：

• src/ ディレクトリ（存在する場合）- メインのソースコード
• tests/ ディレクトリ（存在する場合）- テストファイル

カスタムのプロジェクト構成： target_directories パラメーターを使って、別のディレクトリを指定します。

# For a package-based structure
target_directories = ["mypackage", "tests"]

# For a simple project with code in root
target_directories = ["."]

# For complex multi-module projects
target_directories = ["module1", "module2", "shared", "tests"]

構造化ログ

サーバーは包括的なロギング機能を提供します。

• 開発／デバッグ用の、コンソールへの標準的な人間が読みやすいログ
• 解析や監視用の、ファイルへの構造化 JSON ログ
• パラメーター、実行時間、結果を含む関数呼び出しの追跡
• 完全なスタックトレースを含むエラーコンテキストの自動取得
• 設定可能なログレベル（DEBUG、INFO、WARNING、ERROR、CRITICAL）
• project_dir/logs/mcp_tools_py_{timestamp}.log に作成されるデフォルトのタイムスタンプ付きログファイル

構造化ログエントリーの例：

{
  "timestamp": "2025-08-05 14:30:15",
  "level": "info",
  "event": "Starting pylint check",
  "project_dir": "/path/to/project",
  "target_directories": ["src", "tests"],
  "max_issues": 1
}

簡単な開発時にファイルへのロギングを無効にするには、--console-only を使用します。

MCP クライアントのクイックセットアップ

自動セットアップ（推奨）

1. まずサーバーをインストールします。

   pip install git+https://github.com/MarcusJellinghaus/mcp-tools-py.git
   

2. mcp-config で設定します（別途インストールしてください。このパッケージに含まれているわけではありません）。

   mcp-config
   

   次に「Add New」を選択し、このサーバーを検索します。

プロジェクトディレクトリを尋ねるプロンプトが表示され、MCP クライアントが自動的に設定されます。

注： mcp-config のサーバーレジストリには、まだ mcp-tools-py のエントリーがありません。このサーバーが見つからない場合は、以下の手動セットアップを使用してください。

手動セットアップ

手動で設定する場合は、MCP 設定ファイルを編集します。

Claude Desktop（Windows の場合は %APPDATA%\Claude\claude_desktop_config.json）：

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": ["--project-dir", "/path/to/your/project"]
        }
    }
}

開発モードの場合：

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "python",
            "args": [
                "-m",
                "src.main",
                "--project-dir",
                "/path/to/your/project"
            ],
            "env": {
                "PYTHONPATH": "/path/to/mcp-tools-py"
            }
        }
    }
}

VSCode（.vscode/mcp.json）：

{
    "servers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": ["--project-dir", "."]
        }
    }
}

VSCode の開発モード：

{
    "servers": {
        "mcp-tools-py": {
            "command": "python",
            "args": ["-m", "src.main", "--project-dir", "."],
            "env": {
                "PYTHONPATH": "/path/to/mcp-tools-py"
            }
        }
    }
}

MCP Inspector でテストする

npx @modelcontextprotocol/inspector mcp-tools-py --project-dir /path/to/project

利用可能なツール

サーバーは19個のMCPツールを公開しています。

ツール	機能
run_pylint_check	静的解析を実行し、検出結果をLLMが対応可能なプロンプトとして返します
run_pytest_check	テストスイートを実行し、JSONレポートを解析して失敗を要約します
run_mypy_check	プロジェクトの[tool.mypy]設定に基づいて型チェックを実行し、エラーコードを設定できます
run_ruff_check	読み取り専用のRuffリンター解析を実行します
run_ruff_fix	Ruffの安全な修正をその場で適用します。安全でない修正はオプトインです
run_bandit_check	セキュリティリンターを実行します
run_deptry_check	宣言された依存関係とインポートを照合します（deptry）
run_vulture_check	vulture_whitelist.pyに対して未使用コードを検出します
run_tach_check	tach.tomlに基づいてアーキテクチャ上の境界を検証します
run_lint_imports_check	.importlinterに基づいてインポート契約を検証します
run_format_code	pyproject.tomlの設定に従ってisort、次にblackを実行するか、Ruffのインポートソート、次にruff formatを実行します。check_onlyを指定すると、書き込みを行わずに結果を報告します
list_symbols	ファイル内のトップレベルの関数、クラス、変数を一覧表示します
find_references	プロジェクト全体からシンボルへの参照をすべて検索します
move_symbol	トップレベルのシンボルを別のモジュールに移動し、インポートを更新します
rename_symbol	モジュールレベルのシンボルの名前をプロジェクト全体で変更します
move_module	モジュールを別のパッケージに移動し、参照を更新します
get_library_source	設定済みのプロジェクト環境でドット区切りのインポートパスを解決し、そのソースを返します
search_library_files	標準ライブラリを含む、インストール済みパッケージのソースファイル内をgrepまたはglobで検索します
sleep	指定した秒数だけ実行を一時停止します

pylint、pytest、mypyのパラメーターについては、機能を参照してください。

開発

開発環境のセットアップ

# Clone the repository
git clone https://github.com/MarcusJellinghaus/mcp-tools-py.git
cd mcp-tools-py

# Create and activate a virtual environment
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On Unix/MacOS:
source .venv/bin/activate

# Install dependencies
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

MCP Dev Toolsで実行する

# Set the PYTHONPATH and run the server module using mcp dev
set PYTHONPATH=. && mcp dev src/server.py

ライセンス

このプロジェクトはMIT Licenseの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

MIT Licenseは、最小限の制限で再利用を認める寛容なライセンスです。適切な帰属表示を条件として、使用、コピー、変更、配布を認めています。

リンク

• MCP Python SDK
• MCP Filesystem Tools