Skip to main content
Glama
kwrkb

worklog-mcp

by kwrkb

worklog-mcp

English | 日本語

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

設計思想

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

Keep it Simple

  • データベース不要、すべて平文のMarkdownファイル

  • 複雑な設定や外部依存を排除

  • 可搬性と可読性を最優先

Search First

  • 人間が整理するのではなく、AIが検索して情報を引き出す

  • シンプルなテキストマッチングで過去の知見を発掘

Related MCP server: ai-journal

機能

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


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 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

Available Tools

2 tools
save_worklogA

作業ログ、思考の断片、エラー解決策を保存します。

データは月単位のMarkdownファイル(~/.worklogs/YYYY-MM.md)に追記されます。

Args: content: ログの内容。作業メモ、解決策、思考の断片など。 tags: 関連タグのリスト(任意)。検索時に役立ちます。

Returns: 保存成功メッセージとファイルパスを含む辞書

ParametersJSON Schema
NameRequiredDescriptionDefault
tagsNo
contentYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description reveals that data is appended to monthly Markdown files, providing specific file path structure. This goes beyond a simple 'save' but lacks details on concurrency, limits, or idempotency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a clear structure: purpose first, then storage detail, parameter docs, and return value. No superfluous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool with two parameters and an output schema, the description covers storage mechanism, parameter roles, and return format. No critical information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining both parameters: content (what to log) and tags (optional, for search). This adds crucial meaning beyond the schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the verb 'save' and the resource 'work logs', listing specific examples like thought fragments and error solutions. It clearly distinguishes from the sibling 'search_worklogs' which is for retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage via examples but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusion criteria or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_worklogsA

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

シンプルなテキストマッチング(grep的な挙動)で該当箇所と、 その周辺行(コンテキスト)を抽出して返します。

Args: query: 検索キーワード(正規表現ではなく、プレーンテキスト)

Returns: 検索結果を含む辞書(マッチしたエントリのリスト)

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses grep-like behavior and returns matches with context but does not mention potential performance implications of a full scan, auth requirements, or any destructive actions. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two short paragraphs: one explaining the tool's function and another listing parameters and returns. No unnecessary words, well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple inputs (one parameter) and the presence of an output schema, the description covers the essential behavior. It mentions the return is a dict with matched entries, though details on context line count or format are missing. Mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, but the description adds critical semantics: it specifies that the query parameter is plain text and not a regular expression. This goes beyond the schema's type-only definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool searches past Markdown log files and extracts entries related to a keyword using plain text matching (grep-like). It distinguishes itself from the sibling tool save_worklog, which saves entries, making the purpose specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (searching log files for keywords) and the sibling tool save_worklog provides context for when to save instead. However, it does not explicitly state when not to use it or mention any alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.2.0
    • First observedsave_worklog
    • First observedsearch_worklogs

TDQS

A4.2/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely distinct purposes: one saves worklogs, the other searches them. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern (save_worklog, search_worklogs), making them predictable and easy to use.

Tool Count3/5

With only 2 tools, the server is on the thin side, but for a simple worklog utility it covers the basic needs of saving and searching. It is borderline but not unreasonable.

Completeness3/5

The server provides create (save) and read (search) functionality but lacks update or delete operations, which are notable gaps for a complete worklog lifecycle.

Maintenance

ActivitySlowing
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers