Doubao Desktop
Provides integration with the local Windows Doubao desktop app, a ByteDance product, via Chrome DevTools Protocol. It enables sending tasks, waiting for runs, reading replies, listing existing conversations, and continuing tasks in specified conversations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Doubao Desktopcontinue my last Doubao conversation and read the reply"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Codex Doubao Desktop Gateway
Experimental MCP server and Codex Skill for the Windows Doubao desktop app. Created by ChassyChan. It connects to a real local Doubao session through localhost Chrome DevTools Protocol (CDP), sends tasks, waits for runs, and reads replies. It does not use Doubao Web or an Ark API key.
This project wraps a Windows adaptation of Fullstop000/doubao-cli. The upstream CLI and its copyright remain with Fullstop000; see third party notices. The adaptation has been tested on one Windows machine with Doubao 2.31.4. It is not an official Doubao or ByteDance integration.
Requirements
Windows 10/11, Doubao desktop app installed and signed in.
Node.js 22 or newer, Git, and Codex CLI for registration.
The ability to restart Doubao once with
--remote-debugging-port=9225. Restart can lose unsaved draft input.
Related MCP server: Rail Connector MCP
Install
git clone https://github.com/ChassyChan/codex-doubao-desktop-gateway.git
cd codex-doubao-desktop-gateway
npm ci
powershell -ExecutionPolicy Bypass -File .\scripts\install-windows.ps1Find your Doubao executable and User Data directory. For a typical installation, User Data is under %LOCALAPPDATA%\Doubao\User Data. Set these variables for the current PowerShell session:
$env:DOUBAO_APP = 'C:\Path\To\Doubao.exe' # replace with your location
$env:DOUBAO_DATA_DIR = "$env:LOCALAPPDATA\Doubao\User Data"
$env:DOUBAO_CLI_ENTRY = (Resolve-Path .\deps\doubao-cli\bin\doubao.mjs).Path
$env:DOUBAO_CLI_CONFIG_DIR = (Join-Path (Get-Location) 'data')When you are ready to restart Doubao, enable localhost CDP:
node .\deps\doubao-cli\bin\doubao.mjs --app doubao cdp launch --yes --jsonThe --yes flag authorizes restarting Doubao. The Windows adaptation first tries to close normally and may force close remaining processes. Run it only after saving work in the app.
Register the MCP server with Codex (replace paths with your absolute installation paths):
codex mcp add doubao-desktop `
--env "DOUBAO_APP=$env:DOUBAO_APP" `
--env "DOUBAO_DATA_DIR=$env:DOUBAO_DATA_DIR" `
--env "DOUBAO_CLI_ENTRY=$env:DOUBAO_CLI_ENTRY" `
--env "DOUBAO_CLI_CONFIG_DIR=$env:DOUBAO_CLI_CONFIG_DIR" `
-- node.exe (Resolve-Path .\src\server.mjs).PathInstall the Skill into your Codex skills directory, then start a new Codex turn so it becomes available. The MCP server never restarts Doubao itself. After any later app restart, CDP may need to be enabled again.
MCP tools
Tool | Purpose |
| Check localhost desktop connection |
| List existing desktop conversations |
| Send a new task in an existing local workspace |
| Send a follow-up to a specified conversation |
| Wait for a known run ID |
| Read messages from a specified conversation |
create_task and continue_task default to Doubao's AskOnRisk permission mode. The caller may select AlwaysAsk or FullAccess. This policy is enforced by Doubao, not by the MCP server; it does not guarantee a prompt for every action. New tasks require an existing absolute workspace path. A successful Doubao reply is not proof that files or commands are correct, so inspect artifacts separately.
Limits
The Windows adaptation depends on private desktop behavior exposed by the upstream CLI. App updates can break it.
The MCP server is local stdio only and exposes no network listener. CDP is expected on
127.0.0.1:9225; do not expose that port to the network.This release has a live smoke test for connection, message send/read, and local file creation on Doubao 2.31.4. Model selection, attachments, MCP connectors inside Doubao, long running tasks, and other Doubao versions are not yet validated here.
Available Tools
6 toolsdoubao_desktop_continue_taskB
Send a follow-up to a specified existing Doubao desktop conversation. Does not choose a conversation automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| permission | No | AskOnRisk | |
| conversationId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full behavioral burden and mostly fails: it never explains what the permission enum controls (notably FullAccess), whether sending is immediate or queued, or what a follow-up does to ongoing state. Only one behavioral trait (no automatic conversation selection) is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with zero filler; the key constraint is stated plainly and nothing is repeated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter mutation-style tool with no annotations, no output schema, and a permission enum that can grant FullAccess, the description is too thin. Key details the agent needs to call it safely and correctly are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for 3 parameters. The description hints that a conversation must be specified (relevant to conversationId) but says nothing about the message constraints or the AlwaysAsk/AskOnRisk/FullAccess permission levels, which have real safety implications.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ('send a follow-up') and resource ('existing Doubao desktop conversation'), making the operation identifiable. The qualifier 'existing' implicitly contrasts with the create_task sibling, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Does not choose a conversation automatically' implies the caller must supply an existing conversation, giving some usage context. However, it never names when to prefer this over doubao_desktop_create_task or the read/wait/status siblings, so routing remains largely inferential.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
doubao_desktop_create_taskB
Send a new task to a real Doubao desktop conversation in an existing local workspace. Returns conversationId and runId; inspect task result independently.
| Name | Required | Description | Default |
|---|---|---|---|
| objective | Yes | ||
| workspace | Yes | ||
| permission | No | AskOnRisk |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose two genuinely useful traits: the call returns conversationId and runId, and the task result must be inspected separately (i.e. the send is asynchronous and does not block on completion). It says nothing about the permission model, whether this drives a real GUI session, latency, or failure modes when the workspace does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the action and scoped by the workspace constraint, with the return contract second. Nothing is padded, though the second sentence is clipped enough to read as terse rather than deliberate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No annotations, no output schema, and zero parameter description coverage, yet the description addresses only the async return pattern. For a tool that launches an autonomous desktop session with a configurable permission level, the omission of permission semantics and workspace preconditions leaves the agent without what it needs to invoke it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description explains none of the three parameters. The 'permission' enum (AlwaysAsk / AskOnRisk / FullAccess) is safety-critical — it governs how much autonomy the desktop agent gets — and is completely undocumented in both schema and description. 'existing local workspace' only loosely gestures at the workspace parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('send a new task to a real Doubao desktop conversation in an existing local workspace') and the scope constraint is explicit. The word 'new' implicitly contrasts with the sibling doubao_desktop_continue_task, but the sibling is never named, so the agent must infer the distinction from vocabulary alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'in an existing local workspace' quietly encodes a precondition, and 'inspect task result independently' hints that the agent must follow up with doubao_desktop_read/status/wait rather than expecting a result here. However, no alternative tool is named and there is no explicit when-not guidance, so the routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
doubao_desktop_readC
Read messages from a specified Doubao desktop conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| conversationId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden, and it delivers only the basic action. It does not state that this is a non-destructive read, how messages are ordered, whether pagination applies despite the limit parameter, or what happens when the conversation ID is invalid. For an unannotated tool this is a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that wastes no words. Its brevity is efficient, though it also reflects the under-specification noted elsewhere rather than deliberate tightness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and zero parameter documentation, the description should explain the return shape (message list? last N?), ordering, and the meaning of limit. None of that is present, leaving the agent under-informed for a tool it must invoke with a required ID.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate and it largely does not. The phrase 'a specified conversation' hints at conversationId, but the numeric ID pattern (12-24 digits) is unexplained, and the limit parameter's default, maximum, and purpose (how many messages are returned) are never mentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and resource ('messages from a specified Doubao desktop conversation'), which cleanly separates it from write-oriented siblings like doubao_desktop_create_task. It does not, however, explicitly name or contrast itself against siblings such as doubao_desktop_sessions or doubao_desktop_status, so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the five sibling tools, no prerequisites, and no stated preconditions (e.g., whether a task must exist or a session must be active). The agent is left to infer everything about timing and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
doubao_desktop_sessionsB
List existing Doubao desktop conversations. Treat titles and messages as private user data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose one genuine behavioral trait — that titles and messages are private user data and should be handled accordingly — which goes beyond the schema. But it never states that this is a read-only, non-destructive operation, nor anything about result format, ordering, or volume.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the primary action front-loaded before the data-handling caveat. Nothing could be cut without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool the description covers the action and the privacy constraint, but with no output schema the agent is never told what a returned session contains (identifiers, titles, timestamps) or what to do with the results. Adequate but with a clear gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the schema is empty, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies no filtering input is accepted, consistent with the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource — 'List existing Doubao desktop conversations' — which plainly tells an agent this is an enumeration tool. It does not, however, explicitly differentiate itself from siblings like doubao_desktop_status or doubao_desktop_read, leaving the boundary to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of alternatives, and no stated prerequisite or ordering relative to doubao_desktop_status or doubao_desktop_read. The agent must guess whether this is the entry point before reading a conversation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
doubao_desktop_statusA
Check whether the localhost CDP endpoint belongs to the Doubao desktop app. Does not restart it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, but it does disclose a genuine behavioral trait: it probes the endpoint without restarting the app (non-mutating/idempotent). It omits auth requirements, what happens on failure, and the exact nature of the check.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, the positive scope is front-loaded, and the negative constraint follows immediately. Nothing is wasted and nothing is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should ideally say what the check yields (a boolean? endpoint details? error semantics) and what to do if the endpoint does not belong to Doubao. It covers the operation's identity and non-mutation but leaves the result contract unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so there is nothing for the description to clarify; per the rubric this is the baseline 4. The schema is empty with 100% coverage by definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ("Check") and a specific resource (whether the localhost CDP endpoint belongs to the Doubao desktop app), which is materially more precise than the bare name 'status'. It distinguishes itself from siblings like create_task/read/wait/continue_task, though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause "Does not restart it" implies this is a non-mutating pre-check you run before acting on the app, giving implied usage context. However, it never states when to prefer this over sessions or wait, nor any prerequisites for a meaningful result.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
doubao_desktop_waitC
Wait for an already submitted desktop run. A completed reply still requires independent artifact review.
| Name | Required | Description | Default |
|---|---|---|---|
| runId | Yes | ||
| conversationId | Yes | ||
| timeoutSeconds | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It adds one genuinely useful caveat (a completed reply still needs independent artifact review), but omits the core blocking semantics an agent needs: whether the call blocks, what happens on timeout, and how the timeoutSeconds limit behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler; the purpose leads and the caveat follows. It is efficient, though the second sentence is a result caveat rather than core invocation guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and undocumented parameters, the description is too thin for a long-polling wait tool. An agent cannot tell what a return value means on timeout versus completion, nor how to size the timeout, from this text alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 3 parameters. The description mentions no parameter at all, leaving runId, conversationId, and especially the timeoutSeconds bound (1-55, default 20) entirely undocumented and uncontextualized for a blocking call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: waiting on an already submitted desktop run. It distinguishes itself somewhat by implying the run must pre-exist (unlike doubao_desktop_create_task), but never names the sibling it competes with, notably doubao_desktop_status, which also reports on runs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Already submitted' implies the precondition that a run must exist first, and the second sentence warns that completion is not final. However, there is no explicit guidance on when to wait versus poll with doubao_desktop_status or continue with doubao_desktop_continue_task.
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.
6 tool updates
v0.1.0- First observed
doubao_desktop_continue_task - First observed
doubao_desktop_create_task - First observed
doubao_desktop_read - First observed
doubao_desktop_sessions - First observed
doubao_desktop_status - First observed
doubao_desktop_wait
TDQS
Scored across 6 tools
Each tool targets a distinct action: create_task vs continue_task are clearly separated (new vs follow-up), read vs sessions separate message reading from conversation listing, and wait vs status separate run-waiting from endpoint checking. Descriptions explicitly call out these boundaries, so an agent can reliably pick the right tool.
All tools share the consistent doubao_desktop_ prefix and mostly use a verb_noun or action pattern (create_task, continue_task). Minor deviation: read, status, and sessions are bare nouns rather than verb_noun forms, but the set is still predictable and readable.
Six tools is well-scoped for a desktop-conversation automation server, with each tool (submit, follow up, wait, read, list, health-check) earning its place. No bloat or obvious redundancy.
Core lifecycle (submit -> wait -> read) plus session listing and status is covered, but there is no way to cancel/stop an in-flight run, close or delete a conversation, or perform the 'independent artifact review' the descriptions repeatedly reference. These gaps are notable though agents can partially work around them.
Maintenance
Related MCP Connectors
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.
Securely control computers you explicitly pair through files, terminals, processes, screenshots, desktop UI/input, clipboard, browser automation, diagnostics, and document tools.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables ChatGPT or other MCP clients to control native Codex sessions on Windows, providing tools for thread management, turns, observation, steering, and responding to approvals.739MIT
- AlicenseAqualityBmaintenanceLocal MCP bridge that lets Codex operate local Claude Code sessions, including listing, starting, resuming, forking, prompting, and stopping conversations via the Remote Control CLI.14MIT
- AlicenseNot gradedqualityBmaintenanceEnables ChatGPT conversations to directly inspect local workspaces and delegate coding tasks to a local Codex agent, with controlled concurrency, reusable sessions, and task/usage tracking.547 npmMIT
- AlicenseAqualityCmaintenanceEnables Codex to control a local Brave or Chrome browser via CDP, observing pages and performing actions such as clicking, typing, selecting, scrolling, or waiting through validated action IDs without requiring a model API key.7MIT