git-readonly-mcp
This server provides read-only Git access for AI-assisted code review and analysis (e.g., Kiro, Claude Code). It enforces strict security: only read operations, no arbitrary commands, shell execution, or credential helpers; repository paths are restricted and output sizes are capped.
Repository Management: List configured workspace repositories (
git_list_repositories) and dynamically register worktrees under approved roots (git_register_repository).Status & History: Check working tree status (
git_status), browse filtered commit history (git_log), and inspect commit details with optional patches (git_show_commit).Diffing & Comparison: Compare working tree, index, or any two revisions (
git_diff), compare commit ranges (git_range_diff), and find merge base with ahead/behind counts (git_compare_refs).File & Content Inspection: Blame files line-by-line (
git_blame), search tracked content with regex (git_grep), browse file trees (git_list_tree), and read file content up to 1 MiB at any revision (git_read_file).Refs & Remotes: List branches, tags, and remote-tracking refs (
git_list_refs), view remote names without URLs (git_list_remotes), and fetch refs from public HTTPS remotes only (git_list_remote_refs).
Provides read-only access to Git repositories, enabling inspection of history, diffs, refs, file contents, and repository status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@git-readonly-mcp Show me the diff between develop and main"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Git Readonly MCP
Gitの履歴、差分、参照、ファイル内容をAIセルフレビューへ渡すためのread-only MCPサーバーです。Kiro、Claude Code、Claude Desktop、VS Codeから、同じローカルstdioサーバーを利用できます。
任意のGitコマンド実行機能は公開しません。起動時に許可したworkspace folder、またはrepository root配下に対し、用途別の型付きツールだけを提供します。
Requirements
Node.js 20以上
Git 2.43以上を推奨
信頼できるローカルGitリポジトリ
Related MCP server: TimeVerse Code Reader
Build
npm ci
npm run check
npm run test:integration成果物は依存関係を含む単一ファイルです。
dist/git-readonly-mcp.mjsGitHub Releaseを公開すると、release tagからbuildとtestを実行し、bundle、README、LICENSEを含むzipとSHA-256 checksumをRelease assetsへ添付します。
git-readonly-mcp-<tag>.zip
git-readonly-mcp-<tag>.zip.sha256checksum fileとzipを同じディレクトリへ置き、次のコマンドで検証できます。
sha256sum --check git-readonly-mcp-<tag>.zip.sha256直接起動する場合:
node /path/to/git-readonly-mcp/dist/git-readonly-mcp.mjs \
--workspace-folder /path/to/frontend \
--workspace-folder /path/to/backend \
--repository-root /path/to/projects--workspace-folderを省略した場合は、プロセスの現在ディレクトリだけを候補にします。指定したfolder自体がGit worktreeのルートでなければ利用不可として一覧へ表示し、親や子のリポジトリは自動探索しません。
--repository-rootは、AIがgit_register_repositoryで後から登録できる親ディレクトリです。指定した親そのものと配下だけを許可し、symlinkを解決した実体が範囲外なら拒否します。任意パスを無制限に許可するoptionはありません。
Placement
個人で複数プロジェクトから利用する場合は、bundleをユーザーディレクトリへ1つだけ置く構成を推奨します。
~/.mcp/git-readonly/git-readonly-mcp.mjsMCP設定ではこのbundleを絶対パスで指定し、repositoryの許可範囲だけをclient側の--workspace-folderまたは--repository-rootで渡します。bundleの配置場所とGitへのアクセス許可は分離されています。プロジェクト内への配置は、teamで同じversionを固定し、設定もrepositoryで共有したい場合に適しています。
Client configuration
VS Code
単一root用の設定は .vscode/mcp.json に含まれています。multi-root workspaceでは、workspace folder名を明示します。
{
"servers": {
"git-readonly": {
"type": "stdio",
"command": "node",
"args": [
"/absolute/path/to/git-readonly-mcp.mjs",
"--workspace-folder",
"${workspaceFolder:Frontend}",
"--workspace-folder",
"${workspaceFolder:Backend}",
"--repository-root",
"${workspaceFolder}"
]
}
}
}Kiro
このリポジトリを直接開く場合の設定は .kiro/settings/mcp.json に含まれています。別プロジェクトから利用する場合はbundleとrepositoryを絶対パスで指定します。
提供する15ツールのうち、14個のGit参照ツールはread-onlyとしてautoApproveへ明示的に列挙しています。git_register_repositoryはserverが読める範囲を広げるため、自動承認から除外しています。
{
"mcpServers": {
"git-readonly": {
"command": "node",
"args": [
"/absolute/path/to/git-readonly-mcp.mjs",
"--repository-root",
"/absolute/path/to/projects"
],
"disabled": false,
"autoApprove": [
"git_list_repositories",
"git_status",
"git_log",
"git_show_commit",
"git_diff",
"git_range_diff",
"git_blame",
"git_grep",
"git_list_refs",
"git_list_tree",
"git_read_file",
"git_compare_refs",
"git_list_remotes",
"git_list_remote_refs"
]
}
}
}Claude Code
claude mcp add --transport stdio --scope project git-readonly -- \
node /absolute/path/to/git-readonly-mcp.mjs \
--workspace-folder /absolute/path/to/repositoryまたはproject rootの .mcp.json に設定します。
{
"mcpServers": {
"git-readonly": {
"type": "stdio",
"command": "node",
"args": [
"/absolute/path/to/git-readonly-mcp.mjs",
"--workspace-folder",
"/absolute/path/to/repository"
]
}
}
}Claude Desktop
Developer settingsの claude_desktop_config.json に同じstdio起動設定を追加します。
{
"mcpServers": {
"git-readonly": {
"type": "stdio",
"command": "node",
"args": [
"/absolute/path/to/git-readonly-mcp.mjs",
"--workspace-folder",
"/absolute/path/to/repository"
]
}
}
}Claude Desktop向けのワンクリック配布用 .mcpb は現在の成果物には含まれません。
Tools
Tool | Purpose |
| 設定済みfolderと |
| 許可されたroot配下のworktreeを登録 |
| branch、staged、unstaged、untracked状態を取得 |
| revision、期間、author、message、pathで履歴を検索し、rename前も追跡 |
| commit metadata、stat、path限定可能なpatchを取得 |
| working tree、index、HEAD、2 revisionをcontext行数・rename検出指定で比較 |
| 2つのcommit rangeを比較 |
| fileの行単位attributionを取得 |
| working tree、index、revisionの内容を検索 |
| branch、tag、remote-tracking refを一覧化 |
| revision時点のtreeを一覧化 |
| revision、index、working treeからbounded fileを取得 |
| merge baseとahead/behind件数を取得 |
| URLを開示せずremote名を一覧化 |
| 設定済みpublic anonymous HTTPS remoteのrefを取得 |
最初にgit_list_repositoriesを呼びます。対象が未登録ならgit_register_repositoryへpathを渡し、返されたrepositoryIdを以後のツールへ渡します。ツール結果はstructuredContentとJSON textの両方で返されます。
AI review workflow
rename前を含む対象ファイルの履歴を取得します。followRenamesはpath指定時だけ利用できます。
{
"repositoryId": "project-0123456789ab",
"revision": "HEAD",
"path": "docs/design.md",
"followRenames": true,
"limit": 20
}履歴から選んだcommitを対象ファイルに限定して読みます。
{
"repositoryId": "project-0123456789ab",
"revision": "abc1234",
"path": "docs/design.md",
"includePatch": true,
"contextLine": 8,
"findRenames": true
}HEADから現在のworking treeまでのtracked変更をまとめてレビューします。headはstagedとunstagedを含みますが、untracked fileは含みません。
{
"repositoryId": "project-0123456789ab",
"mode": "head",
"path": "docs/design.md",
"format": "patch",
"contextLine": 8,
"findRenames": true
}git_diffの他のmodeは、workingがindex対working tree、stagedがHEAD対index、revisionsがbase対headです。mergeBase: trueを指定したrevisionsはmerge baseからheadまでを比較します。
作業中またはuntrackedの設計書全文はworking treeから読みます。
{
"repositoryId": "project-0123456789ab",
"target": "working",
"path": "docs/design.md",
"maxBytes": 262144
}git_read_file.targetはrevision(既定)、index、workingから選択します。revisionだけがrevision入力を利用し、workingはsymlink解決後もrepository内にあるfileだけを読みます。
Security model
Gitはshellを介さず
spawnします。pager、external diff、textconv、credential helper、interactive prompt、optional lock、lazy fetchを抑止します。
revision rangeは個別parameterからサーバー側で構築します。
file pathはrepository-relative literalだけを許可します。
動的repository登録は、起動時の
--repository-rootをcanonical pathで検証した配下だけに制限します。local queryは既定15秒、blameとrange-diffは30秒、remote queryは10秒で停止します。
stdoutは1 MiB、stderrは64 KiBを上限とします。
remote問い合わせは設定済みremote名だけを受け取り、資格情報のないHTTPS URLかつpublic IPへ解決される場合だけ
ls-remoteを実行します。SSH、HTTP、file URL、private/local address、fetch、pull、push、cloneは許可しません。
このサーバーはsandboxではありません。Git自体が読むrepository metadataを含め、信頼できるworkspaceだけを登録してください。
Development
npm run dev -- --workspace-folder /path/to/repository
npm run lint
npm run typecheck
npm test
npm run build
npm run test:integration
npm run pack:dry-runMCP Inspectorで確認する場合:
npx @modelcontextprotocol/inspector node dist/git-readonly-mcp.mjs \
--workspace-folder /path/to/repositoryログはstderrへ出力してください。stdio MCPのstdoutへ診断メッセージを出すとJSON-RPC通信が壊れます。
Available Tools
15 toolsgit_blameARead-onlyIdempotent
Show line-level commit attribution for a file.
Inputs: path (required), repositoryId (required), end, start, +1 more. Returns: error, output, truncated
git_compare_refsBRead-onlyIdempotent
Resolve two refs and report merge base and ahead/behind counts.
Inputs: left (required), right (required), repositoryId (required). Returns: error, output, truncated
git_diffBRead-onlyIdempotent
Compare working tree, index, HEAD, or two revisions.
Inputs: repositoryId (required), base, head, mode, +5 more. Returns: error, output, truncated
git_grepBRead-onlyIdempotent
Search tracked content without invoking a shell.
Inputs: pattern (required), repositoryId (required), path, target, +3 more. Returns: error, output, truncated
git_list_refsBRead-onlyIdempotent
List local branches, tags, and remote-tracking refs.
Inputs: repositoryId (required), kind, limit. Returns: error, output, truncated
git_list_remote_refsARead-onlyIdempotent
List refs from a configured anonymous public HTTPS remote.
Inputs: remote (required), repositoryId (required), limit. Returns: error, output, truncated
git_list_remotesARead-onlyIdempotent
List configured remote names without exposing URLs.
Inputs: repositoryId (required). Returns: error, output, truncated
git_list_repositoriesList Git repositoriesARead-onlyIdempotent
List configured workspace folders and whether each is an available Git repository root.
Inputs: no named parameters. Returns: repositories
git_list_treeBRead-onlyIdempotent
List files and directories at a revision.
Inputs: repositoryId (required), path, revision, recursive. Returns: error, output, truncated
git_logCRead-onlyIdempotent
Read bounded commit history.
Inputs: repositoryId (required), to, from, path, +10 more. Returns: error, output, truncated
git_range_diffCRead-onlyIdempotent
Compare two commit ranges.
Inputs: newBase (required), newHead (required), oldBase (required), oldHead (required), +1 more. Returns: error, output, truncated
git_read_fileARead-onlyIdempotent
Read a bounded file from a revision, the index, or the working tree.
Inputs: path (required), repositoryId (required), target, maxBytes, +1 more. Returns: error, output, truncated
git_register_repositoryRegister Git repositoryCRead-onlyIdempotent
Register a Git worktree under a configured repository root and return its repositoryId.
Inputs: path (required). Returns: repository
git_show_commitARead-onlyIdempotent
Show commit metadata, changed files, and optionally its patch.
Inputs: repositoryId (required), path, revision, contextLine, +2 more. Returns: error, output, truncated
git_statusARead-onlyIdempotent
Show branch and working tree status.
Inputs: repositoryId (required). Returns: error, output, truncated
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct read-only Git operation: history, diffs, blame, search, refs, file access, and remotes. Potentially similar tools like diff vs range_diff and log vs show_commit are clearly separated by their descriptions and expected usage.
All tool names follow the consistent git_ prefix with a verb_noun pattern in lowercase snake_case. Composite names like list_remote_refs and range_diff are predictable extensions of the established convention.
Fifteen tools is at the high end of the ideal range, but each tool covers a distinct capability needed for comprehensive read-only Git inspection. No tool feels redundant or ornamental.
The surface covers repository discovery, status, history, commit inspection, diffs, blame, search, refs, tree browsing, file reading, comparison, and remote inspection. For a read-only Git server, this is a complete and coherent feature set with no obvious dead ends.
Maintenance
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
A MCP server built for developers enabling Git based project management with project and personal…
Read-only MCP server exposing a user ORANO library to their own AI agent.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server for AI coding agents to inspect repositories, audit code quality, route engineering skills, and plan safe issue/PR workflows.1MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server for code reading with intelligent caching, line-range selection, and language detection, enabling AI assistants to efficiently and safely explore file systems.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for fast, bounded, read-only Git evidence, enabling AI agents to query commit history, diffs, status, and snapshots by parsing repository storage directly.345 npmMIT
- AlicenseNot gradedqualityDmaintenanceA local-first MCP server that provides read-only access to Git repository history, exposing commit metadata and optionally content patches via configurable policies, with optional AI-powered analysis while never modifying Git state.12 npmApache 2.0