worklog-mcp

English | 日本語

<a name="japanese"></a>

シンプルで検索可能なMarkdownベースの作業ログMCPサーバー。

設計思想

「ログを取るのは億劫だが、過去の解決策は検索したい」

Keep it Simple

• データベース不要、すべて平文のMarkdownファイル
• 複雑な設定や外部依存を排除
• 可搬性と可読性を最優先

Search First

• 人間が整理するのではなく、AIが検索して情報を引き出す
• シンプルなテキストマッチングで過去の知見を発掘

機能

worklog-mcpは2つのMCPツールのみを提供します：

1. save_worklog - ログを保存

作業ログ、思考の断片、エラー解決策を月単位のMarkdownファイル（~/.worklogs/YYYY-MM.md）に保存します。

パラメータ:

• content (必須): ログの内容
• tags (任意): 関連タグのリスト

保存形式:

### 2026-01-03 14:30:00
Tags: #python #mcp #refactoring

worklog-mcpをMarkdownベースに完全リファクタリング。
SQLiteを削除し、平文管理に変更。

2. search_worklogs - ログを検索

過去のMarkdownファイルを全走査し、キーワードに関連するエントリを抽出します。

パラメータ:

• query (必須): 検索キーワード（大文字小文字を無視）

検索ロジック:

• ディレクトリ内の.mdファイルを新しい順に走査
• シンプルなテキストマッチング（grep的な挙動）
• マッチしたエントリ全体を返す

インストール

GitHubから直接インストール（推奨）

# uvがない場合は先にインストール
curl -LsSf https://astral.sh/uv/install.sh | sh

# GitHubから直接インストール
uv tool install git+https://github.com/kwrkb/worklog-mcp

ローカルからインストール

# リポジトリをクローンしてインストール
git clone https://github.com/kwrkb/worklog-mcp.git
cd worklog-mcp
uv tool install .

pipを使用

pip install git+https://github.com/kwrkb/worklog-mcp

MCPサーバーとして使用

Claude Code（claude mcp addコマンド）

最も簡単な方法は claude mcp add コマンドを使用することです。

uvxを使用（インストール不要）

# グローバルに追加（すべてのプロジェクトで使用可能）
claude mcp add worklog -s user -- uvx --from git+https://github.com/kwrkb/worklog-mcp worklog-mcp-server

# プロジェクト固有で追加（現在のプロジェクトのみ）
claude mcp add worklog -- uvx --from git+https://github.com/kwrkb/worklog-mcp worklog-mcp-server

インストール済みの場合

# グローバルに追加
claude mcp add worklog -s user -- worklog-mcp-server

# プロジェクト固有で追加
claude mcp add worklog -- worklog-mcp-server

追加後、claude mcp list で確認できます：

claude mcp list

Claude Code（手動設定）

~/.claude/settings.json に追加:

{
  "mcpServers": {
    "worklog": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kwrkb/worklog-mcp", "worklog-mcp-server"]
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "worklog": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kwrkb/worklog-mcp", "worklog-mcp-server"]
    }
  }
}

VS Code (Roo Code / Cline)

VS Code で MCP を使用するには、Roo Code や Cline などの拡張機能を使用します。 拡張機能の設定画面（MCP Servers）で以下のように設定してください。

{
  "mcpServers": {
    "worklog": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/kwrkb/worklog-mcp",
        "worklog-mcp-server"
      ]
    }
  }
}

Gemini CLI

Gemini CLI は gemini mcp add コマンドまたは設定ファイルの編集でMCPサーバーを追加できます。

コマンドで追加

# グローバルに追加（すべてのプロジェクトで使用可能）
gemini mcp add -s user worklog uvx --from git+https://github.com/kwrkb/worklog-mcp worklog-mcp-server

# プロジェクト固有で追加
gemini mcp add worklog uvx --from git+https://github.com/kwrkb/worklog-mcp worklog-mcp-server

Windows の場合:

gemini mcp add -s user worklog uvx "--from" "git+https://github.com/kwrkb/worklog-mcp" "worklog-mcp-server"

手動設定

~/.gemini/settings.json（グローバル）または .gemini/settings.json（プロジェクト）に追加:

{
  "mcpServers": {
    "worklog": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kwrkb/worklog-mcp", "worklog-mcp-server"]
    }
  }
}

使い方

Claude Code の場合（自動ログ保存）

Claude Code では、Claude が自動的に重要な情報を判断して保存します：

• バグ解決や実装完了などの重要な作業
• 有用なデバッグ手法の発見
• ユーザーが明示的に依頼したとき

あなたがすることは何もありません。 Claude が勝手に記録してくれます。

Gemini CLI や他の AI の場合（初回プロンプト）

Gemini CLI や Claude Desktop など、CLAUDE.md を自動読み込みしない環境では、最初に以下のプロンプトを伝えてください：

worklog-mcp の使い方：

【いつログを保存すべきか】
- トリッキーなバグを解決したとき
- 有用なデバッグ手法を発見したとき
- 重要な実装作業を完了したとき
- 予期しない問題の解決策を見つけたとき
- 私が明示的に保存を依頼したとき

【何をログすべきか】
- 洞察と解決策に焦点を当てる（ルーチン作業は記録しない）
- コンテキストを含める：問題は何か、何がうまくいったか、何がうまくいかなかったか
- 検索性のために説明的なタグを使う（例：#python, #debugging, #git）

【ログすべきでないもの】
- ルーチンのファイル編集や書き込み
- シンプルな bash コマンド
- テスト実行
- 学習価値のない標準的な操作

【哲学】
質より量 - 後で検索する価値があるものだけを保存してください。

この指示を伝えれば、どの AI も適切なタイミングでログを保存してくれます。

MCPツールの使用例

MCPサーバーを設定後、Claude Code、Claude Desktop、Gemini CLI から以下のツールが利用できます。

save_worklog - ログを保存

「Pythonのエラーハンドリングの解決策をメモ」
→ save_worklog(content="try-except でログ出力を追加することでデバッグしやすくなった", tags=["python", "debugging"])

「今日やったリファクタリングを記録」
→ save_worklog(content="server.pyをMarkdownベースに書き換え。SQLite削除でコードが150行に削減", tags=["refactoring", "mcp"])

search_worklogs - ログを検索

「Pythonに関する過去のメモを探して」
→ search_worklogs(query="python")

「エラーハンドリングの解決策を検索」
→ search_worklogs(query="try-except")

データ保存場所

ログデータは ~/.worklogs/YYYY-MM.md に保存されます。

カスタム保存先

WORKLOG_DIR 環境変数でカスタムパスを指定できます：

export WORKLOG_DIR=~/Documents/worklogs

クラウド同期（Google Drive, Dropbox など）

シンボリックリンクを使って複数デバイス間で同期できます：

# Mac/Linux
ln -s ~/Google\ Drive/worklogs ~/.worklogs

# Windows (管理者PowerShell)
mklink /D "C:\Users\<user>\.worklogs" "G:\My Drive\worklogs"

アンインストールとクリーンアップ

アンインストール

# uv tool でインストールした場合
uv tool uninstall worklog-mcp

# pip でインストールした場合
pip uninstall worklog-mcp

データのクリーンアップ

# デフォルト保存先の削除
rm -rf ~/.worklogs/

# カスタム保存先を使用している場合
rm -rf $WORKLOG_DIR

MCP設定から削除

Claude Code:

# グローバル設定から削除
claude mcp remove worklog -s user

# プロジェクト設定から削除
claude mcp remove worklog

Gemini CLI:

# グローバル設定から削除
gemini mcp remove worklog -s user

# プロジェクト設定から削除
gemini mcp remove worklog

手動削除の場合:

• Claude Code: ~/.claude/settings.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) または %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Gemini CLI: ~/.gemini/settings.json または .gemini/settings.json

---

<a name="english"></a>

worklog-mcp (English)

Simple, searchable Markdown-based worklog MCP server.

Philosophy

"Recording logs is tedious, but searching past solutions is valuable"

Keep it Simple

• No database, everything is plain Markdown files
• No complex configuration or external dependencies
• Portability and readability first

Search First

• Let AI search and extract information, not humans organizing
• Simple text matching to discover past insights

Features

worklog-mcp provides only 2 MCP tools:

1. save_worklog - Save logs

Save work logs, thought fragments, and error solutions to monthly Markdown files (~/.worklogs/YYYY-MM.md).

Parameters:

• content (Required): Log content
• tags (Optional): List of related tags

Storage format:

### 2026-01-03 14:30:00
Tags: #python #mcp #refactoring

Completely refactored worklog-mcp to Markdown-based.
Removed SQLite and switched to plain text management.

2. search_worklogs - Search logs

Scan all past Markdown files and extract entries related to keywords.

Parameters:

• query (Required): Search keyword (case-insensitive)

Search logic:

• Scan .md files in directory (newest first)
• Simple text matching (grep-like behavior)
• Return entire matching entries

Installation

Install directly from GitHub (Recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install directly from GitHub
uv tool install git+https://github.com/kwrkb/worklog-mcp

Install locally

# Clone the repository and install
git clone https://github.com/kwrkb/worklog-mcp.git
cd worklog-mcp
uv tool install .

Using pip

pip install git+https://github.com/kwrkb/worklog-mcp

Usage as an MCP Server

Claude Code (claude mcp add command)

The easiest way is to use the claude mcp add command.

Using uvx (No installation required)

# Add globally (available in all projects)
claude mcp add worklog -s user -- uvx --from git+https://github.com/kwrkb/worklog-mcp worklog-mcp-server

# Add per project (current project only)
claude mcp add worklog -- uvx --from git+https://github.com/kwrkb/worklog-mcp worklog-mcp-server

If already installed

# Add globally
claude mcp add worklog -s user -- worklog-mcp-server

# Add per project
claude mcp add worklog -- worklog-mcp-server

After adding, you can verify with claude mcp list:

claude mcp list

Claude Code (Manual Configuration)

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "worklog": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kwrkb/worklog-mcp", "worklog-mcp-server"]
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "worklog": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kwrkb/worklog-mcp", "worklog-mcp-server"]
    }
  }
}

VS Code (Roo Code / Cline)

To use MCP in VS Code, use extensions like Roo Code or Cline. Configure the extension settings (MCP Servers) as follows:

{
  "mcpServers": {
    "worklog": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/kwrkb/worklog-mcp",
        "worklog-mcp-server"
      ]
    }
  }
}

Gemini CLI

Gemini CLI supports adding MCP servers via the gemini mcp add command or by editing the settings file.

Using commands

# Add globally (available in all projects)
gemini mcp add -s user worklog uvx --from git+https://github.com/kwrkb/worklog-mcp worklog-mcp-server

# Add per project
gemini mcp add worklog uvx --from git+https://github.com/kwrkb/worklog-mcp worklog-mcp-server

On Windows:

gemini mcp add -s user worklog uvx "--from" "git+https://github.com/kwrkb/worklog-mcp" "worklog-mcp-server"

Manual configuration

Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project):

{
  "mcpServers": {
    "worklog": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kwrkb/worklog-mcp", "worklog-mcp-server"]
    }
  }
}

Usage

For Claude Code (Automatic Logging)

In Claude Code, Claude automatically judges and saves important information:

• After solving tricky bugs or completing significant work
• When discovering useful debugging techniques
• When you explicitly request to save something

You don't need to do anything. Claude will record automatically.

For Gemini CLI and Other AIs (Initial Prompt)

For environments that don't automatically read CLAUDE.md (like Gemini CLI or Claude Desktop), provide this prompt at the beginning:

How to use worklog-mcp:

[When to save logs]
- After solving a tricky bug or error
- When discovering useful debugging techniques
- After completing significant implementation work
- When finding solutions to unexpected problems
- When I explicitly request to save something

[What to log]
- Focus on insights and solutions, not routine operations
- Include context: what was the problem, what worked, what didn't
- Use descriptive tags for searchability (e.g., #python, #debugging, #git)

[What NOT to log]
- Routine file edits or writes
- Simple bash commands
- Test executions
- Standard operations without learning value

[Philosophy]
Quality over quantity - save only what's worth searching later.

After providing this instruction, any AI will save logs at appropriate times.

MCP Tool Usage Examples

After configuring the MCP server, the following tools are available from Claude Code, Claude Desktop, or Gemini CLI.

save_worklog - Save logs

"Note Python error handling solution"
→ save_worklog(content="Adding log output in try-except made debugging easier", tags=["python", "debugging"])

"Record today's refactoring"
→ save_worklog(content="Rewrote server.py to Markdown-based. Removed SQLite, code reduced to 150 lines", tags=["refactoring", "mcp"])

search_worklogs - Search logs

"Find past notes about Python"
→ search_worklogs(query="python")

"Search for error handling solutions"
→ search_worklogs(query="try-except")

Data Storage Location

Log data is stored at ~/.worklogs/YYYY-MM.md.

Custom Storage Location

Use WORKLOG_DIR environment variable to specify a custom path:

export WORKLOG_DIR=~/Documents/worklogs

Cloud Sync (Google Drive, Dropbox, etc.)

Use symlinks to sync worklogs across devices:

# Mac/Linux
ln -s ~/Google\ Drive/worklogs ~/.worklogs

# Windows (PowerShell as Admin)
mklink /D "C:\Users\<user>\.worklogs" "G:\My Drive\worklogs"

Uninstall and Cleanup

Uninstall

# If installed with uv tool
uv tool uninstall worklog-mcp

# If installed with pip
pip uninstall worklog-mcp

Data Cleanup

# Remove default storage location
rm -rf ~/.worklogs/

# If using custom storage location
rm -rf $WORKLOG_DIR

Remove from MCP Configuration

Claude Code:

# Remove from global settings
claude mcp remove worklog -s user

# Remove from project settings
claude mcp remove worklog

Gemini CLI:

# Remove from global settings
gemini mcp remove worklog -s user

# Remove from project settings
gemini mcp remove worklog

Manual removal:

• Claude Code: ~/.claude/settings.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Gemini CLI: ~/.gemini/settings.json or .gemini/settings.json

License

MIT License