Git Worklog Mcp
Overview
git-worklog-mcp
一个 MCP (Model Context Protocol) 服务器，让 AI 从 Git 提交历史自动生成专业的工作日志。
特性
- AI 智能分析 - AI 理解代码变更语义，生成有价值的工作描述
- 可配置模板 - 支持日报、周报、月报等预设模板，支持自定义模板文件
- 统一工具前缀 - 所有工具使用
worklog_前缀，方便唤起 - 多语言支持 - 支持中文 (zh) 和英文 (en) 输出
- 零配置启动 - 通过 npx 直接运行，无需安装
快速开始
方式一：npx 直接使用（推荐）
无需安装，在 MCP 配置中直接使用 npx：
{
"mcpServers": {
"git-worklog": {
"command": "npx",
"args": ["git-worklog-mcp"]
}
}
}
方式二：全局安装
npm install -g git-worklog-mcp
安装后配置：
{
"mcpServers": {
"git-worklog": {
"command": "git-worklog-mcp"
}
}
}
MCP 配置文件位置
| 工具 | 配置文件路径 |
|---|---|
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Cursor | ~/.cursor/mcp.json |
| VS Code | .vscode/mcp.json 或用户级 MCP 配置 |
配置选项详解
完整配置示例
{
"mcpServers": {
"git-worklog": {
"command": "npx",
"args": [
"git-worklog-mcp",
"--template", "daily",
"--lang", "zh"
]
}
}
}
所有参数说明
| 参数 | 简写 | 环境变量 | 说明 | 可选值 | 默认值 |
|---|---|---|---|---|---|
--template | -t | WORKLOG_TEMPLATE | 预设模板名称 | daily, weekly, monthly, simple | daily |
--template-file | -f | WORKLOG_TEMPLATE_FILE | 自定义模板文件的绝对或相对路径 | 任意 .md 文件路径 | - |
--author | -a | WORKLOG_AUTHOR | 默认筛选的 Git 作者（可用名字或邮箱） | 字符串 | - |
--lang | -l | WORKLOG_LANG | 输出语言，影响分类名称显示 | zh（中文）, en（英文） | zh |
优先级:
--template-file>--template（当指定模板文件时，预设模板参数被忽略）
配置示例
示例 1：最简配置（中文日报）
{
"mcpServers": {
"git-worklog": {
"command": "npx",
"args": ["git-worklog-mcp"]
}
}
}
示例 2：周报模式
{
"mcpServers": {
"git-worklog": {
"command": "npx",
"args": [
"git-worklog-mcp",
"--template", "weekly",
"--lang", "zh"
]
}
}
}
示例 3：指定作者 + 英文输出
{
"mcpServers": {
"git-worklog": {
"command": "npx",
"args": [
"git-worklog-mcp",
"-t", "daily",
"-a", "your-name@example.com",
"-l", "en"
]
}
}
}
示例 4：使用自定义模板文件
{
"mcpServers": {
"git-worklog": {
"command": "npx",
"args": [
"git-worklog-mcp",
"--template-file", "D:\\projects\\.worklog-template.md"
]
}
}
}
macOS/Linux 路径示例：
{
"args": [
"git-worklog-mcp",
"-f", "/Users/yourname/projects/.worklog-template.md"
]
}
示例 5：使用环境变量配置
{
"mcpServers": {
"git-worklog": {
"command": "npx",
"args": ["git-worklog-mcp"],
"env": {
"WORKLOG_TEMPLATE": "monthly",
"WORKLOG_AUTHOR": "cherish",
"WORKLOG_LANG": "zh"
}
}
}
}
可用工具
配置完成后，AI 可以调用以下工具（均以 worklog_ 为前缀）：
| 工具名 | 说明 |
|---|---|
worklog_get_data | 核心工具 - 获取 Git 提交数据，返回结构化 JSON + 模板内容供 AI 生成日志 |
worklog_get_diff | 获取指定提交的代码差异（diff），用于深入分析变更内容 |
worklog_list_authors | 列出仓库的所有贡献者及其提交统计 |
worklog_get_template | 获取当前配置的模板信息，查看可用模板列表 |
worklog_get_data 参数
| 参数 | 必填 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
repo_path | ✅ | string | Git 仓库路径 | "D:\\my-project" 或 "." |
author | ❌ | string | 按作者筛选 | "your-name" |
since | ❌ | string | 开始日期 | "yesterday", "1 week ago", "2024-01-01" |
until | ❌ | string | 结束日期 | "today", "2024-01-31" |
max_commits | ❌ | number | 最大提交数量 | 50（默认 100） |
使用方法
配置好 MCP 后，直接对 AI 说：
生成今日工作日志
请用 worklog_get_data 获取 D:\my-project 仓库今天的提交，按模板生成工作日志
生成本周周报
请获取 D:\my-project 仓库最近一周的 Git 提交，生成周报
生成指定作者的月报
请获取仓库 2024 年 1 月 cherish 的所有提交，生成月度工作报告
查看当前模板配置
请调用 worklog_get_template 查看当前使用的模板
预设模板
daily - 日报模板
按分类展示今日工作内容，适合每日汇报：
# 工作日志 - {{date_range}}
## 今日概要
- 提交次数: {{total_commits}}
- 代码变更: +{{total_insertions}}/-{{total_deletions}} 行
## 工作内容
### 功能开发
- {{message}} (`{{short_hash}}`)
### Bug 修复
- ...
weekly - 周报模板
按周汇总，包含分类统计和模块分布，适合周会汇报：
# 周报 - {{date_range}}
## 本周概览
| 指标 | 数值 |
|------|------|
| 提交次数 | {{total_commits}} |
| 活跃天数 | {{active_days}} 天 |
## 工作分类
### {{category_name}} ({{count}}项)
- {{message}}
monthly - 月报模板
完整的月度工作报告，含统计表格，适合月度总结：
# 月度工作报告 - {{month}}
## 月度总览
- 总提交: {{total_commits}} 次
- 活跃天数: {{active_days}} 天
## 工作分类统计
| 类型 | 数量 | 占比 |
|------|------|------|
| {{name}} | {{count}} | {{percentage}}% |
simple - 简单列表
极简模式，仅列出提交信息，适合快速查看：
# 工作记录 {{date_range}}
- {{message}}
- {{message}}
共 {{total_commits}} 项
自定义模板
方式一：使用模板文件（推荐）
- 创建模板文件
在项目中创建 .worklog-template.md：
# 我的工作日志 - {{date_range}}
## 今日完成
{{#each commits}}
- [{{date_formatted}}] {{message}} (`{{short_hash}}`)
- 变更: {{stats.files_changed}} 文件, +{{stats.insertions}}/-{{stats.deletions}}
{{/each}}
## 统计汇总
- 提交: {{total_commits}} 次
- 代码变更: +{{total_insertions}}/-{{total_deletions}} 行
- 涉及模块: {{module_count}} 个
---
*由 AI 自动生成*
- 在 MCP 配置中指定模板文件
{
"args": [
"git-worklog-mcp",
"--template-file", "/path/to/.worklog-template.md"
]
}
方式二：通过环境变量指定
{
"env": {
"WORKLOG_TEMPLATE_FILE": "/path/to/template.md"
}
}
模板语法
| 语法 | 说明 | 示例 |
|---|---|---|
{{variable}} | 变量替换 | {{total_commits}} |
{{#each items}}...{{/each}} | 循环遍历数组 | {{#each commits}}...{{/each}} |
{{#category:名称}}...{{/category}} | 按分类筛选提交 | {{#category:功能开发}}...{{/category}} |
可用变量一览
汇总变量（全局可用）
| 变量 | 说明 | 示例值 |
|---|---|---|
{{date_range}} | 日期范围 | 2024-01-01 ~ 2024-01-07 |
{{total_commits}} | 总提交数 | 15 |
{{total_insertions}} | 新增代码行数 | 342 |
{{total_deletions}} | 删除代码行数 | 128 |
{{active_days}} | 活跃天数 | 5 |
{{module_count}} | 涉及模块数量 | 8 |
提交变量（在 {{#each commits}} 中使用）
| 变量 | 说明 | 示例值 |
|---|---|---|
{{hash}} | 完整提交哈希 | a1b2c3d4e5f6... |
{{short_hash}} | 短哈希（7位） | a1b2c3d |
{{message}} | 提交信息 | feat: add user login |
{{date_formatted}} | 格式化日期 | 2024-01-15 |
{{category_name}} | 分类名称 | 功能开发 |
{{author.name}} | 作者名 | cherish |
{{author.email}} | 作者邮箱 | xxx@example.com |
{{stats.files_changed}} | 变更文件数 | 3 |
{{stats.insertions}} | 新增行数 | 45 |
{{stats.deletions}} | 删除行数 | 12 |
分类变量（在 {{#each categories}} 中使用）
| 变量 | 说明 | 示例值 |
|---|---|---|
{{name}} | 分类名称 | 功能开发 |
{{count}} | 该分类的提交数 | 8 |
{{percentage}} | 占比百分比 | 53 |
模块变量（在 {{#each modules}} 中使用）
| 变量 | 说明 | 示例值 |
|---|---|---|
{{name}} | 模块名称（基于文件路径首级目录） | src |
{{count}} | 变更次数 | 12 |
工作原理
┌─────────────┐ ┌─────────────────┐ ┌─────────────┐
│ Git 仓库 │ ──▶ │ MCP Server │ ──▶ │ AI │
│ 提交历史 │ │ 数据 + 模板 │ │ 智能生成 │
└─────────────┘ └─────────────────┘ └─────────────┘
- MCP 提取数据 - 从 Git 仓库读取提交历史，自动分类
- 返回结构化数据 - JSON 格式的提交数据 + 模板内容
- AI 智能生成 - AI 按模板格式，用专业语言描述每项工作的价值
自动分类规则
基于 commit message 的前缀或关键词自动判断：
| 分类 | 触发关键词 |
|---|---|
| 功能开发 | feat、add、new |
| Bug修复 | fix、bug、issue |
| 代码优化 | refactor、optimize、improve |
| 文档更新 | docs、readme、document |
| 测试相关 | test |
| 代码风格 | style、format、lint |
| 日常维护 | chore、deps、upgrade |
| 性能优化 | perf、performance |
常见问题
Q: 如何只获取我自己的提交？
使用 --author 参数，可以填写 Git 用户名或邮箱：
{
"args": ["git-worklog-mcp", "-a", "your-email@example.com"]
}
Q: 模板文件路径怎么写？
- Windows:
"D:\\project\\.worklog-template.md"或"D:/project/.worklog-template.md" - macOS/Linux:
"/home/user/project/.worklog-template.md" - 相对路径:
"./.worklog-template.md"（相对于启动 MCP 的工作目录）
Q: 支持哪些 AI 工具？
支持所有兼容 MCP 协议的工具：
- Claude Desktop
- Cursor
- VS Code + Copilot（需配置 MCP）
- 其他 MCP 兼容客户端
Q: 为什么提交统计显示 0？
首次提交（没有父提交）无法计算 diff，这是正常的。后续提交会正常显示统计。
开发
# 克隆仓库
git clone https://github.com/CherishMvp/git-worklog-mcp.git
cd git-worklog-mcp
# 安装依赖
npm install
# 开发模式（监听文件变化）
npm run dev
# 构建
npm run build
# 使用 MCP Inspector 测试
npm run inspect
License
MIT
Server Config
{
"mcpServers": {
"git-worklog": {
"command": "npx",
"args": [
"git-worklog-mcp",
"--template",
"daily",
"--lang",
"zh"
]
}
}
}Project Info
Created At
5 months agoUpdated At
5 months agoAuthor Name
CherishMvpStar
-Language
-License
-Tags
Recommend Servers
View AllMnemom
2 days ago
PDFGate
@pdfgate
19 hours ago
K Data Gate
@loved0543-dotcom
2 days ago
Playwright Mcp
@microsoft
Playwright MCP server
TypeScript
10 months ago
Memory
@modelcontextprotocol
a year ago
Mcp Server Chatsum
@chatmcp
summarize chat message
typescript
a year ago
Amap Maps
@amap
高德地图官方 MCP Server
a year ago
Docwand
2 days ago