TakeFlow Local Connector · Setup Guide
Contents (10 sections)
This guide covers installation, daily use, and troubleshooting for the TakeFlow local connector. Once Section 3 is complete, you can simply describe what you need in natural language — no commands or parameters to memorise.
A web version is available at
接入指南-EN.htmlin the same folder. It contains the same content and supports printing.中文版:
接入指南.md/接入指南.html.
| Audience | Operators using TakeFlow seats |
| Applies to | Local connector v2.4.0 |
| Reading guide | Sections 2–3 for first-time installation; Sections 4–5 for daily use; Section 6 for troubleshooting |
1. What the Connector Does for You
After installation, the AI assistant can operate your TakeFlow seats directly, within the permissions you grant:
- List seats and their expiry dates
- Power seats on or off, and open the live screen of a seat
- Calculate renewal costs and place renewal orders
- Publish videos or images to the TikTok account of a given seat
- Update account avatar, nickname, bio, and website
- Query post performance data
- Check in bulk whether TikTok accounts still exist (ban check)
- Analyse screen recordings of failed tasks to help identify the cause
The connector works with WorkBuddy, Codex, Claude Desktop, Cursor, DeepSeek Harness, and other desktop clients that can run local programs. Install once and it works across all of them. Cloud-only products such as ChatGPT cannot load a local connector; see Section 6 for the reason and the alternative.
Three notes on how it runs:
| No server required | The connector runs on your own computer |
| No review wait | Unzip, run the installer, and you are ready |
| Data stays local | Credentials are stored on your machine; requests go directly from your computer to the platform |
2. Before You Begin
1. A computer with internet access
macOS, Windows, and Linux are all supported.
2. Node.js 18 or later
Run node -v in a terminal (Command Prompt on Windows):
- A version such as
v18.x,v20.x, orv22.xmeans you are good to go. - If the command is not found, download the LTS release from https://nodejs.org/en and run the command again after installation.
3. A TakeFlow account
This is the phone number and password you normally use to sign in to TakeFlow.
ffmpeg is optional and only needed for the "screen recording diagnosis" feature. If you only analyse screenshots, you can skip it. To install:
brew install ffmpegon macOS, orwinget install Gyan.FFmpegin PowerShell on Windows.
4. Python 3 (optional)
Only needed for the "ban check" feature. Run python3 --version; 3.8 or later is sufficient. macOS and most Linux distributions include it. On Windows, install from https://www.python.org/downloads/.
3. Installation
Step 1: Extract to a Fixed Folder
After extraction you will see two folders:
TakeFlow-MCP— the program itself; keep this folder.文档— copies of this guide and related documents (including the Chinese edition). It can be moved or deleted without affecting the connector.
Suggested locations:
- macOS / Linux:
~/TakeFlow-MCP - Windows:
D:\TakeFlow-MCP
Two things to keep in mind:
- Do not run it from your Downloads folder; the system may clean that directory.
- Do not delete or move the folder after installation. The client configuration points to this path, and moving it requires reinstalling.
Step 2: Run the Installer
| System | How to run |
|---|---|
| macOS | Double-click 一键安装.command. The system may block it on first run; see 3.1 |
| Windows | Double-click 一键安装.bat. If Windows SmartScreen appears, click "More info" → "Run anyway" |
| Linux | Open a terminal in the folder and run bash 一键安装.sh |
3.1 macOS Blocks the Installer on First Run
The installer is not signed with an Apple developer certificate, so macOS shows the following on first launch:
Apple could not verify "一键安装.command" is free of malware that may harm your Mac or compromise your privacy.
This is the standard warning for unsigned scripts, not a virus alert. Allow it once as follows:
- Click "OK" to dismiss the dialog.
- Open System Settings → Privacy & Security.
- In the Security section, you will see "已阻止「一键安装.command」以保护 Mac" with an "Open Anyway" button next to it.
- Click "Open Anyway" and authenticate with your password or Touch ID.
- Double-click
一键安装.commandagain and click "Open" in the dialog.
If "Open Anyway" does not appear, right-click the file, choose "Open", then check again. If it still will not run, open a terminal in the folder and run
bash 一键安装.sh. This method is not affected by the double-click restriction.
3.2 The Installer Asks Four Questions
- API address — press Enter to use the default.
- Phone number — enter the phone number of your TakeFlow account and press Enter.
- Password — nothing is displayed while you type, including asterisks. This is expected. Press Enter when finished.
- Clients to configure — the installer asks about WorkBuddy, Codex, Claude Desktop, Cursor, and DeepSeek Harness in turn. Answer
yornfor each. WorkBuddy, plus Codex and DeepSeek Harness when their directories are detected, default to yes; Claude Desktop and Cursor default to no.
When finished, you will see:
✓ Login successful, credentials saved
✓ Connection verified, 8 seats found in your account
✓ Installation complete!
"Installation complete" means you are done. The number of seats reflects your own account.
3.3 You Can Close the Terminal Afterwards
Yes. The terminal is only used to run the installer. The connector is not a background service; the client starts it on demand and it exits when the call finishes.
- Closing the window does not affect the connector.
- No reinstallation is needed after a reboot.
- Re-run the installer in only two cases: (1) the token expires after 30 days; (2) the installation folder is moved.
"Process completed" at the bottom of the window means the program exited normally.
Step 3: Restart Your Client and Verify
Quit the client completely and reopen it. For WorkBuddy, quit the entire application (Cmd+Q on macOS, or "Quit" from the tray icon on Windows); closing the window alone is not enough.
Then run a test request:
Show me my TakeFlow seats and highlight the ones expiring soon
The client may ask for permission to use the connector on the first call; allow it. If the seat list comes back, installation and connection are complete.
4. Everyday Usage Examples
Every scenario below can be handled in a single sentence. The AI assistant works out the steps; you do not need to know the underlying tools or parameters.
Listing Seats and Expiry Dates
What seats do I have, and which ones are expiring soon?
You will get seat numbers, bound accounts, follower counts, expiry dates, and power status. Seats nearing expiry are flagged separately.
Powering On, Powering Off, and Viewing the Screen
Power on seat 16 and send me the screen link when it is ready
The assistant confirms the target seat, powers it on, waits for the screen to become available, and returns a console link. Open the link and sign in once with your TakeFlow account to view the screen.
Note: seats are powered off when not in use. This does not affect scheduled tasks — the platform powers them on before a task starts and off after it finishes, with no manual intervention.
Renewals
How much does it cost to renew seat 29 for 3 months?
You will receive the plan and the amount payable (including fees). The order is placed only after you confirm, and a payment link is provided. You can then ask the assistant to check the order status.
Uploading and Publishing
Publish the file
new-product.mp4on my desktop to seats 52 and 53, reusing the previous caption
This takes two steps: the platform selects materials by folder and cannot target a single file, so the file must first be uploaded to a cloud folder, and the publishing task is then created from that folder.
You only need to confirm: which seats, how many items are in the folder, publish now or scheduled time, and the title and caption. The assistant handles everything else.
Rules worth knowing before publishing:
- The number of seats multiplied by posts per account must not exceed the number of files in the folder; if it does, you will be asked to add materials.
- Scheduled publishing uses Beijing time; times in the past cannot be submitted.
- For background music, say "add a trending track" or name the song. No music is added unless you ask.
- Files uploaded before are deduplicated automatically and take no extra space.
- Supported formats: mp4, mov, jpg, jpeg, png; maximum 2 GB per file.
Updating Account Profiles
Replace the avatar of seat 16 with this image and change the nickname to your_nickname
The avatar is uploaded to cloud storage, its URL is obtained, and the profile is updated automatically. You do not need to handle formats yourself. Fields you do not mention are left unchanged: changing only the avatar keeps the nickname and bio as they are.
Querying Performance Data
How are the recent posts on seat 52 performing?
You will get an account overview (followers, likes, post count) plus data for the 10 most recent posts.
Two notes:
- Image carousel posts often show 0 plays because the data source does not track them; this does not mean publishing failed.
- Data is unstable within 24 hours of publishing. Allow 24–48 hours before drawing conclusions.
Analysing Failed Tasks
Why did yesterday's task fail to publish? (attach the recording path or link)
Please analyse this screenshot and tell me where it got stuck.
The assistant extracts key frames, compares them against the rule library, and returns four sections: analysis result, key frames, core judgement, and mitigation suggestions.
Checking Whether Accounts Are Banned
Please check whether these TikTok accounts still exist: @user123, @user456, @user789
Each account receives one of four verdicts — exists, not found, exists but all zeros, or unconfirmed — along with nickname, post count, and follower count. Ten accounts take about two minutes, which is normal.
Two notes:
- "Not found" does not always mean banned. Suspension, deletion, platform reclamation, and a username change all look identical at the API level. If you can provide the numeric account ID (uid), the assistant can verify further: a uid that resolves means the account was only renamed; a uid that does not resolve means the account is truly gone.
- This feature uses a public third-party lookup service. It only checks account existence and does not touch your TakeFlow account data.
Other Common Requests
Check the login status of all seats and sign in any that are offline
Create a daily activity task for seats 2 and 19, starting at 9:00 tomorrow morning
Add a customer record and enable CLAW
5. Operations That Require Your Confirmation
For the four categories below, the assistant restates the operation and waits for your confirmation before executing:
| Category | Examples | How confirmation looks |
|---|---|---|
| Cost involved | Renewal orders | "Renew seat 29 for 3 months, total ¥xxx including fees. Confirm the order?" |
| Outbound content | Publishing posts, changing avatar or nickname | "Publish 1 item each to seats 52 and 53, tomorrow at 10:00, titled xxx. Confirm?" |
| State changes | Power on/off, bulk sign-in, daily activity tasks | "About to power on seat 16. Confirm?" |
| File uploads | Uploading materials, creating folders | "About to upload xxx.mp4 to the folder '20261026'. Confirm?" |
In short: anything involving money, account state, or public-facing content is confirmed with you first.
6. Troubleshooting
Check the current version first (Section 8). Including it when you contact support will speed things up.
Double-clicking the Installer Does Nothing
- macOS: the file may lack execute permission. Open a terminal in the folder and run
chmod +x 一键安装.command, then try again. - Alternatively, run
bash 一键安装.shin a terminal. This is not affected by the double-click restriction.
Node.js Not Detected
Node.js is not installed, or the version is below 18. Install the LTS release from https://nodejs.org/en and run the installer again.
TakeFlow Does Not Appear in the Client After Installation
Check in this order:
- Did you fully quit and restart the client? Closing the window alone is not enough.
- In WorkBuddy, open Plugins → MCP Servers and check that the
takeflowentry is healthy (green). Red indicates a configuration problem. - In the installation folder, run
node server/takeflow-mcp.mjsin a terminal. No output is normal; pressCtrl+Cto exit. If an error appears, send it to support.
"Credentials Not Configured" or "Token Expired"
Run the installer again to sign in. Tokens expire every 30 days as a platform security measure; this is not a fault.
Login Fails with "Incorrect Account or Password"
Make sure you are using your TakeFlow platform account, not a TikTok account. If the phone number is not registered, the installer offers to sign up with the same password; answer y.
Image or Video Upload Fails
- Format: only mp4, mov, jpg, jpeg, png are supported.
- Size: maximum 2 GB per file.
- Space: if cloud storage is full, clean it up in the platform web console first.
- If you see "cos-credentials not enabled", no action is needed — the connector automatically falls back to another upload method.
Screen Recording Diagnosis Reports Missing ffmpeg
Install ffmpeg as described in Section 2 and restart the client. Screenshot-only analysis does not require it.
Ban Check Cannot Find python3
This feature requires Python 3.8 or later. Install it as described in Section 2, item 4, then run the request again. If your computer does not allow installing Python, you can skip this feature; everything else still works.
Company Computers Do Not Allow Installing Node.js
Ask IT to use a portable Node build (unzip and run, no installation), and point the command field in the client configuration to that node binary. See the appendix.
Can ChatGPT Use This Connector Directly?
No. ChatGPT runs in the cloud and cannot launch programs on your computer. This connector runs locally, with credentials and operations staying on your machine, so it cannot be added to ChatGPT.
Using it inside ChatGPT would require a separate public gateway — domain, certificate, authentication, and ongoing operations. That is an independent service with its own cost, billed separately from the local package. WorkBuddy, Codex, Claude Desktop, Cursor, and DeepSeek Harness are desktop clients and are not affected.
7. Data and Privacy
- Credentials stay on your machine. They are stored in
~/.takeflow/config.jsonwith 600 permissions (readable only by you) and are never uploaded to any server. - Passwords are not stored. The password you enter is used only to obtain a token and is discarded immediately afterwards.
- Account passwords never leave your machine. When signing in offline seats in bulk, account credentials and two-factor codes are read and submitted locally, never passed to the AI.
- Links carry no tokens. The console and purchase pages are ordinary URLs; sign in normally the first time you open them.
- Direct uploads. Files go from your computer straight to object storage with no relay server. Temporary upload keys exist only in memory and expire after about one hour.
8. Version, Upgrade, and Uninstall
Checking the Current Version
Any one of these three methods works:
- Check the archive name — for example
TakeFlow-MCP-本地接入包-v2.4.0-20261119.zip. The number aftervis the version; the last 8 digits are the build date (10 November 2026). - Run the installer — the first line shows the version. You can close the window immediately; nothing is changed.
- Ask the AI assistant — "What version of the TakeFlow connector is installed, and how long until the token expires?" returns the details for your machine.
Including the version when you contact support will speed up diagnosis.
Component Versions
The package bundles one connector and six skills:
| Component | Version | Purpose |
|---|---|---|
| Local connector | v2.4.0 | Installer and MCP service |
| takeflow | 2.3.0 | Seats, power, renewals, tasks, materials, publishing, profiles, performance data |
| seats-check | 1.0.0 | Seat sign-in and account checks |
| cultivation-task | 1.0.0 | Daily activity tasks |
| client-info | 1.0.0 | Customer record entry |
| tiktok-auto-ops-diagnostic | 1.1.2 | Screen-recording diagnosis of failed tasks |
| tiktok-ban-check | 1.0.0 | Account ban checks |
Skills ship with the package and are not upgraded separately.
Upgrading
Extract the new package over the existing folder (or into a new folder), run the installer again, then restart your client. Existing configuration and skills are backed up automatically. The local edition does not update itself; upgrades are manual.
Uninstalling
- Delete the
~/.takeflowdirectory (on macOS, pressCmd+Shift+Gin Finder, enter~/.takeflow, and press Return). - Open the client's MCP configuration and remove the
takeflowentry (DeepSeek Harness users should remove thetakeflow-mcpentry from~/.dsh/profiles/<profile>/cordis.patch.yml). - WorkBuddy users should also delete six folders under
~/.workbuddy/skills/:takeflow,seats-check,cultivation-task,client-info,tiktok-auto-ops-diagnostic, andtiktok-ban-check. DeepSeek Harness users should delete the same folders under~/.dsh/skills/.
9. Legal and Compliance Notice
This section explains the relationship between the connector and third-party platforms and trademarks, together with the limits of responsibility when you use it. Please read it before use.
Third-Party Names and Icons
The names, icons, interface screenshots, and trademarks of WorkBuddy, Codex, Claude, DeepSeek Harness, and other products that appear in this guide, the installation package, or the accompanying demonstration video belong to their respective owners. They are used only to describe the connector's compatibility and configuration locations. Their use does not imply any affiliation, partnership, agency, sponsorship, or endorsement, nor any certification or recommendation of this product by those companies. Such use does not challenge their rights; if a rights holder considers the usage inappropriate, we will adjust or remove it promptly upon notice.
MCP Is an Open, General-Purpose Protocol
The Model Context Protocol (MCP) is an open technical protocol and is not proprietary to this product. This connector is implemented according to that protocol and can therefore be called from MCP-capable clients. Evolution of the protocol itself, including version changes and compatibility, is determined by its specification maintainers. "MCP support" indicates technical compatibility only; it does not mean that any platform has certified, listed, or recommended this product.
Comply with Each Platform's Terms
When connecting to and using any AI platform, you must also comply with that platform's user agreement, developer terms, usage policies, and the laws and regulations of your jurisdiction. Each platform decides unilaterally — and may change, restrict, or discontinue at any time — the scope of MCP support, configuration method, available features, and rate limits. This product cannot guarantee continued availability on any platform and is not responsible for such platform decisions.
Scope of Use
This connector is intended solely for operating TakeFlow and TikTok accounts that you own or are authorised to manage. Do not use it to circumvent platform risk controls or review, to mass-register or trade accounts, to publish unlawful content, or for any other activity that breaches platform rules or applicable law. You are responsible for the operations performed under your accounts and their consequences.
Third-Party Data and Services
Playback statistics, ban-check results, and similar outputs come from third-party public data sources and may be delayed, truncated, or incomplete. They are provided for operational reference only and do not constitute an official platform conclusion or legal evidence.
Limitation of Responsibility
This guide describes technical integration only and does not grant any authorisation, agency, or warranty with respect to any third-party platform. Where client version changes, platform rule changes, network conditions, or third-party data source failures cause integration failures, limited functionality, or data discrepancies, we will assist with diagnosis but are not liable for indirect losses arising from them.
Appendix: Manual Configuration for IT
This section is for IT staff. Regular users only need to run the installer as described in Section 3.
A1. Obtaining a Token Manually
curl -X POST https://saas.takeflows.com/admin-api/system/tk-auth/login \
-H 'Content-Type: application/json' \
-d '{"phoneNumber":"13800000000","password":"your-password"}'
Write the returned accessToken and refreshToken into ~/.takeflow/config.json and set its permissions to 600:
{
"baseUrl": "https://saas.takeflows.com",
"phoneNumber": "13800000000",
"accessToken": "the returned accessToken",
"refreshToken": "the returned refreshToken",
"expiresTime": 1792633796480
}
A2. Client Configuration
| Client | Configuration file |
|---|---|
| WorkBuddy | ~/.workbuddy/mcp.json (Windows: %USERPROFILE%\.workbuddy\mcp.json) |
| Codex CLI | ~/.codex/config.toml |
| Claude Desktop | macOS ~/Library/Application Support/Claude/claude_desktop_config.json; Windows %APPDATA%\Claude\claude_desktop_config.json |
| Cursor | ~/.cursor/mcp.json |
| DeepSeek Harness | ~/.dsh/profiles/<profile>/cordis.patch.yml (the desktop profile is desktop) |
{
"mcpServers": {
"takeflow": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/TakeFlow-MCP/server/takeflow-mcp.mjs"],
"env": { "TAKEFLOW_HOME": "/Users/your-name/.takeflow" }
}
}
}
[mcp_servers.takeflow]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/TakeFlow-MCP/server/takeflow-mcp.mjs"]
[mcp_servers.takeflow.env]
TAKEFLOW_HOME = "/Users/your-name/.takeflow"
# DeepSeek Harness: written to cordis.patch.yml inside the profile directory
- id: takeflow-mcp
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: takeflow
transport: stdio
command: "/absolute/path/to/node"
args:
- "/absolute/path/to/TakeFlow-MCP/server/takeflow-mcp.mjs"
env:
TAKEFLOW_HOME: "/Users/your-name/.takeflow"
toolCallTimeoutMs: 300000
failOnStartupError: true
Three extra points for DeepSeek Harness: edit cordis.patch.yml, not the cordis.yml beside it; fully quit and relaunch the app after installing, since the plugin tree is composed only at startup; and keep toolCallTimeoutMs above the 60-second default, otherwise video frame extraction will be cut off while the clip downloads.
Two notes:
commandmust be the absolute path to node (find it withwhich nodeorwhere node). GUI clients do not inherit your shell environment variables.- Do not remove other MCP servers from an existing configuration; just append the
takeflowblock.
A3. Codex Skill Index
Codex has no skill mechanism, so the installer maintains an index block in ~/.codex/AGENTS.md between <!-- takeflow-skills:start --> and the matching end marker. It tells the model which document to read in which situation. Content outside the block is left untouched.
For detailed fields and parameters, see
README.mdin the same folder.
If you run into problems during installation or use, send a screenshot of the terminal error to support, or simply ask the AI assistant: "I got the following error while installing the TakeFlow connector — how do I fix it?"
接入指南-EN.md. Edit the Markdown and regenerate; do not edit this file directly.