Threads Analytics｜免費開源、可自架的 Threads 數據分析工具。連接 Access Token，用詳細圖表與指標深入了解你的貼文表現。

繁體中文 · English · 日本語

--- ## 目錄 - [功能](#功能) - [macOS 桌面版](#macos-桌面版) - [快速開始](#快速開始) - [取得 Threads Access Token](#取得-threads-access-token) - [MCP Server](#mcp-server) - [部署](#部署) - [Docker Compose](#docker-compose) - [Docker](#docker) - [Vercel](#vercel) - [自動同步](#自動同步) - [更新既有部署](#更新既有部署) - [開發設定](#開發設定) - [分析功能說明](#分析功能說明) - [授權條款](#授權條款) --- ## 功能 - **今日** — 今天的所有數據都在同一頁：今日貼文的合計、待回覆留言與粉絲變化、發文節奏與最佳時段、今天每篇貼文的完整數據、昨天的貼文與今天新增的部分，以及今日留言收件匣，標出還在等你回覆的留言（即時從 Threads 讀取，不會儲存） - **總覽** — 數據卡（觀看、讚、回覆、轉發、引用、分享、互動率）含相對上期的漲跌幅、觀看趨勢圖（日／週／月）、最佳發文時段推薦、高曝光貼文 - **分析** — 橫跨**成效**、**內容**與**受眾**三個分頁的 31 張圖表 - **貼文** — 可搜尋、可篩選的列表，點選後展開單篇詳細分析，包含發文後第一週的成長曲線 - **抽獎** — 從貼文留言抽出得獎者，可疊加條件（關鍵字、標記好友、截止時間、每個帳號限一次），直接在自己的儀表板完成 - **MCP server** — 讓 Claude 等 AI agent 透過 OAuth 保護的端點查詢你的分析數據 - 多帳號支援，可隨時切換 - 可設定自動同步間隔 - Access Token 自動續期 — 連接一次即可，不用每 60 天手動重貼 - 密碼保護（單一環境變數 `APP_PASSWORD`） - 繁體中文 / English / 日本語介面，支援淺色、深色與自動外觀

總覽 · 帳號表現一目了然	今日 · 今天的貼文，以及還在等你回覆的留言
分析 · 帳號觀看依來源拆分	貼文 · 每篇貼文發布後第一週的成長
受眾 · 粉絲成長與粉絲分布	抽獎 · 從貼文留言抽出得獎者

--- ## macOS 桌面版配備 Apple Silicon（M1 或更新晶片）的 Mac 可以直接從 [GitHub Releases](https://github.com/ridemountainpig/threads-analytics/releases) 下載桌面版，不需要自行安裝 Node.js、pnpm 或 PostgreSQL。目前尚未提供 Intel Mac 版本。下載、首次開啟、更新與解除安裝步驟請參閱 [Mac 版 App 說明](https://threads-analytics.app/zh-TW/desktop)。如需從原始碼建置桌面版，請參閱[桌面版 README](./desktop/README-zh.md)。 --- ## 快速開始最快取得線上實例的方式是 Railway 一鍵部署模板 — 會自動建立 PostgreSQL 資料庫並設定好必要的環境變數： [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/zibjsX?referralCode=vPBCb4&utm_medium=integration&utm_source=template&utm_campaign=generic) 也可以交給 AI coding agent（Claude Code、Codex、Cursor…）代勞 — 每個 agent 部署指南都附有現成的 prompt，貼給 agent 就會自動建立資料庫、完成部署並回報網址：[Railway](https://threads-analytics.app/zh-TW/deploy/railway-agent) · [Vercel](https://threads-analytics.app/zh-TW/deploy/vercel-agent) 已經有自己的伺服器？[Docker Compose](#docker-compose) 一個指令就能把應用程式和 PostgreSQL 一起啟動；已經有資料庫的話，也可以直接執行預建映像檔（詳見 [Docker](#docker)）。服務啟動後，用 `APP_PASSWORD` 登入並連接 Threads 帳號 — 見下一節。想從原始碼執行請見[開發設定](#開發設定)。 --- ## 取得 Threads Access Token 1. 前往 [developers.facebook.com](https://developers.facebook.com) 建立含有 **Access the Threads API** use case 的應用程式 2. 產生**Access Token** 3. 在儀表板中：**設定 → 新增 Threads 帳號 → 貼上 Token** 詳細圖文步驟請參考：[如何生成 Threads Access Token](https://threads-analytics.app/zh-TW/token-guide)。 Token 有效期限為 60 天，應用程式會自動幫你續期： - 每次同步時會檢查 token，當剩餘效期少於 30 天就自動延長 60 天（Threads API 只允許更新產生超過 24 小時的 token）。 - 設定頁面的帳號卡片會顯示 token 的有效期限與上次自動更新時間。 - 若 token 仍然過期（例如應用程式停止太久沒有同步），設定頁面會顯示警示；此時請重新產生 token，並在帳號卡片上點擊**更新 Token**貼上，已同步的資料會完整保留。 --- ## MCP Server Dashboard 內建一個遠端 [MCP](https://modelcontextprotocol.io) server（`/api/mcp`，Streamable HTTP），讓 Claude 等 AI agent 直接查詢你已同步的 Threads 資料——貼文、聚合分析與追蹤者歷史——回答問題或撰寫成效報告。所有工具皆為**唯讀**。 ### 連接 AI agent 驗證採用 OAuth 2.1（PKCE + Dynamic Client Registration），不需要複製任何 API key。首次連接時 client 會自行註冊，瀏覽器會開啟 dashboard 登入頁（`APP_PASSWORD`），登入後在同意畫面核准存取即可。 **Claude Code** ```bash claude mcp add --transport http threads-analytics https://your-deployment.example.com/api/mcp ``` 接著在 Claude Code 內執行 `/mcp` 完成 OAuth 登入。 **Claude（網頁版／桌面版）** — 設定 → Connectors → **Add custom connector**，貼上 `https://your-deployment.example.com/api/mcp`。已連接的 client 會顯示在**設定 → 已連接的 agent**，隨時可以撤銷。 ### 工具 | 工具 | 功能 | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_account_overview` | 所有已連接帳號的名稱、同步狀態、貼文數、資料日期範圍與追蹤者成長摘要——建議的第一個呼叫 | | `list_posts` | 貼文列表含指標；支援日期範圍、排序（日期／觀看／讚／互動率）、媒體類型篩選、全文搜尋與分頁 | | `get_post` | 單篇貼文完整資訊，含全文，以及發文後 1 小時、3 小時、6 小時、12 小時、24 小時、48 小時與 7 天的成效 | | `compare_post_growth` | 在相同的發文後時間點（例如發文 24 小時）比較貼文，並與你的中位數排名；尚未到達該時間點的新貼文，也會和其他貼文同一時間點的表現比較，看是領先還是落後 | | `get_analytics` | 指定日期範圍內的 31 個聚合分析 section（最佳發文時段、關鍵字分析、觀看分佈、發文連續紀錄等），可只取需要的 | | `get_follower_history` | 每日追蹤者快照與成長摘要，可選擇附上最新受眾組成 | | `compare_periods` | 兩個期間的核心指標對照，附絕對與百分比變化，含帳號總觀看；比較期間預設為主要期間正前方的等長視窗 | | `get_monthly_review` | 單一月份對照比較月份（預設上個月，也可指定任何更早的月份，例如去年同月）與前幾個月的基準：KPI、最佳／最差貼文、漲粉日、內容組合、串文與逐週趨勢；傳入上月的實驗即可逐一判定成效 | 連接多個帳號時，除了 `get_account_overview` 以外的每個工具都接受 `account` 參數（帳號名稱或 id）。若未提供，工具會回傳帳號清單，讓 agent 先問你要查哪一個，而不是自行猜測。以 `YYYY-MM-DD` 指定的日期代表分析時區（預設 Asia/Taipei；桌面 App 使用 Mac 的系統時區）的一整天；`list_posts`、`compare_post_growth`、`get_analytics`、`compare_periods` 與 `get_monthly_review` 也接受 `timezone` 參數，改用其他時區解讀。貼文成長資料（`get_post` 的各時間點成效與 `compare_post_growth`）來自每次同步在貼文發布後 30 天內記錄的成效——發文初期最密每 15 分鐘一筆，後期每天一筆。從加入這項功能的版本才開始記錄，更早發布的貼文沒有成長資料；同步越頻繁，貼文初期的曲線就越細。 ### Prompts Server 也註冊了現成的 prompts，多數接受選填的 `period` 參數（如 `30d`、`90d` 或日期區間）；`monthly-review` 則接受 `month`（`YYYY-MM`）與選填的 `previous_experiments`（上月月報的實驗）： | Prompt | 產出內容 | | ---------------------- | --------------------------------------------------------------------------------------------------------------- | | `performance-review` | 完整成效報告：趨勢、最佳／最差貼文與改善行動 | | `content-strategy` | 哪些格式、長度與主題有效，並給出建議的內容組合 | | `posting-schedule` | 依受眾互動時間推薦的具體每週發文排程 | | `viral-post-breakdown` | 深入解析爆紅貼文，萃取可複製的模式 | | `audience-insights` | 追蹤者成長與受眾組成，以及對內容和時段的啟示 | | `topic-analysis` | 哪些主題與寫作模式帶動成效，並附新貼文點子 | | `monthly-review` | 月報：為上月的實驗打分數並提出三個新實驗；實驗由你這端保存（例如 `threads-reviews/YYYY-MM.md`），不會寫入伺服器 | --- ## 部署網站上的[自架部署教學](https://threads-analytics.app/zh-TW/deploy/self-host)會一步步說明這一節的所有內容：Docker Compose、Docker、從原始碼執行、Vercel Cron、環境變數、自動同步與更新。 ### Docker Compose [`docker-compose.yml`](./docker-compose.yml) 會把儀表板和它專用的 PostgreSQL 一起跑起來，不必先準備資料庫。在空資料夾裡下載這個檔案，並在旁邊寫一個 `.env`： ```bash curl -fsSLO https://raw.githubusercontent.com/ridemountainpig/threads-analytics/main/docker-compose.yml cat > .env <`，`/api/cron/sync` 會用這個值驗證請求來源是否合法。 ### 自動同步在長時間運行的部署環境（Docker / VPS / Railway）設定 `SYNC_SCHEDULER_ENABLED=true`（Docker Compose 已經幫你設好），內建 scheduler 會隨伺服器啟動，並依照 Settings 中設定的間隔自動同步所有已連接的帳號（不只是使用中的那一個）。Vercel 請改用上方的 cron 設定。 ### 更新既有部署新版本會以更新後的 Docker 映像檔發佈，使用官方映像檔的部署在有新版時會於儀表板顯示更新提示。資料庫 migration 會在啟動時自動執行，因此更新只需要取得新的映像檔或程式碼： - **Docker Compose** — 在放著 `docker-compose.yml` 的資料夾裡執行： ```bash docker compose pull docker compose up -d ``` - **Docker / VPS** — 拉取最新映像檔，停掉舊 container 後用相同參數重新啟動： ```bash docker pull ghcr.io/ridemountainpig/threads-analytics:latest ``` - **Railway** — 在 Railway Dashboard 對服務觸發重新部署。 - **從原始碼部署** — `git pull` 後執行 `pnpm install && pnpm prisma:generate && pnpm build`，再以 `pnpm start` 重新啟動（會自動執行 migration）。 - **Vercel** — 推送新版本即可，migration 會如上所述在建置階段執行。每個正式版本的映像檔也會標上版本號，例如 `1.0.0`，另有 `1.0` 與 `1` 指向該系列的最新版本，因此 Docker 與 Docker Compose 部署可以用這些 tag 固定版本，而不是 `latest`（Compose 請修改 `image:` 那一行）。各版本的變更內容請見 [GitHub Releases](https://github.com/ridemountainpig/threads-analytics/releases)。更新過程中資料庫（貼文、洞察資料、帳號）都會完整保留。 --- ## 開發設定系統需求：Node.js 22.12+ 或 24+、pnpm、PostgreSQL 資料庫。 ### 1. 複製專案並安裝套件 ```bash git clone https://github.com/ridemountainpig/threads-analytics.git cd threads-analytics pnpm install pnpm prisma:generate ``` ### 2. 設定環境變數 ```bash cp .env.example .env.local ``` 接著填入各項數值： | 變數 | 說明 | 產生方式 | | ------------------------ | ----------------------------------------- | ---------------------- | | `APP_PASSWORD` | 登入儀表板的密碼 | 自行設定任意字串 | | `DATABASE_URL` | PostgreSQL 連線字串 | 由你的資料庫服務提供 | | `TOKEN_ENCRYPTION_KEY` | 加密存放在資料庫中的 Threads Access Token | `openssl rand -hex 32` | | `CRON_SECRET` | 正式環境用來保護 `/api/cron/sync` | 隨機 16 字以上字串 | | `SYNC_SCHEDULER_ENABLED` | 啟用內建背景同步 scheduler | Docker/VPS 設為 `true` | ### 3. 執行資料庫 migration ```bash npx prisma migrate dev ``` ### 4. 啟動開發伺服器 ```bash pnpm dev ``` 開啟 [http://localhost:3000](http://localhost:3000)，用 `APP_PASSWORD` 登入。 ### 5. 連接 Threads 帳號 1. 點擊側邊欄的**設定** 2. 點擊**新增 Threads 帳號** 3. 貼上你的 Threads Access Token（取得方式見[取得 Threads Access Token](#取得-threads-access-token)） 4. 新增完成後會自動開始首次同步（可能需要幾分鐘） ### 常用指令 ```bash pnpm dev # 啟動開發伺服器 pnpm build # 建置正式版 pnpm start # 執行資料庫 migration 並啟動正式伺服器 npx prisma studio # 開啟資料庫 GUI npx prisma migrate dev --name <名稱> # 建立新的 migration ``` --- ## 分析功能說明儀表板在總覽、分析（成效／內容／受眾）與貼文頁面共提供 31 張圖表。可以到[網站](https://threads-analytics.app/zh-TW/analytics)用示範資料瀏覽；每張圖表的內容說明，以及受眾指標背後的取樣規則，完整記錄在**[分析功能說明](./docs/analytics-zh.md)**。 --- ## 授權條款 Threads Analytics 以 [GNU Affero General Public License v3.0](./LICENSE) 開源。你可以自由地自架、修改與再散布 — 但若你以修改後的版本對外提供網路服務，必須以相同授權公開其原始碼。