twidb

Twitter アーカイブデータを DuckDB に取り込み、CLI や Claude Desktop / Claude Code から検索・集計・分析できるツール。

• ローカル完結（外部 API への通信なし）
• DuckDB の列指向エンジンで高速クエリ
• Claude Desktop には MCP 経由、Claude Code には SKILL.md 経由で連携

インストール

pipx install .

使い方

アーカイブの取り込み

twidb import ~/Downloads/twitter-archive.zip

初回・更新とも同じコマンド。既存データは上書きされる。tweets と likes（いいね）を取り込む。

DB 状態確認

twidb status

クエリ実行

# JSON 出力（デフォルト）
twidb query "SELECT created_at, full_text FROM tweets WHERE full_text ILIKE '%DuckDB%' ORDER BY created_at DESC LIMIT 20"

# テーブル形式出力
twidb query --table "SELECT year_month, COUNT(*) AS cnt FROM tweets GROUP BY year_month ORDER BY year_month"

DB 削除

twidb delete

確認ダイアログの後、DB ファイルを削除する。

スキーマ

tweets テーブル

CREATE TABLE tweets (
    id                    VARCHAR PRIMARY KEY,
    created_at            TIMESTAMP,         -- UTC
    full_text             TEXT,
    lang                  VARCHAR(10),
    like_count            INTEGER,
    retweet_count         INTEGER,
    reply_to_id           VARCHAR,            -- 返信先 tweet_id
    reply_to_screen_name  VARCHAR,            -- 返信先ユーザー名
    is_retweet            BOOLEAN,
    year_month            VARCHAR(7),         -- '2024-03' 形式
    raw_json              JSON                -- 元データ全体
);

likes テーブル

アーカイブの data/like.js から取り込む。タイムスタンプや投稿者情報はアーカイブに含まれない。

CREATE TABLE likes (
    tweet_id    VARCHAR PRIMARY KEY,
    full_text   TEXT,
    url         VARCHAR,
    raw_json    JSON
);

Claude Desktop MCP 設定

mcp-server-motherduck を使用して Claude Desktop から直接クエリできる。

Claude Desktop の設定ファイルに以下を追加:

OS	設定ファイルのパス
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "twidb": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "<HOME>/.twidb/twitter.duckdb"
      ]
    }
  }
}

• <HOME> は自分のホームディレクトリの絶対パスに置き換えること（例: /Users/alice, C:\Users\alice）
• uvx のフルパスを指定すると確実（例: macOS では /opt/homebrew/bin/uvx）

Claude Code からの利用（SKILL.md）

SKILL.md を配置すると、Claude Code が Twitter アーカイブ関連の質問に自動で twidb query を使えるようになる。

mkdir -p ~/.claude/skills/twidb
cp /path/to/twidb/SKILL.md ~/.claude/skills/twidb/SKILL.md

ライセンス

MIT