freebuff-mcp
This server exposes a Freebuff bridge for inspecting projects, threads, messages, files, and status, plus controlling existing threads.
Check Freebuff/bridge status and list models (
freebuff_status,list_models).List projects and threads (
list_projects,list_threads).Read thread metadata, visible messages, and active work (
get_thread,get_thread_messages,get_active_work).List safe project files and read one project file (
list_project_files,read_project_file).Send a prompt to an existing thread (
send_message).Stop or resume a thread (
stop_thread,resume_thread).Change an existing thread's model or reasoning effort (
set_model,set_reasoning).
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., "@freebuff-mcp list my recent Freebuff projects and their threads"
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.
Freebuff MCP
Watch the short video to see the path from request to finished work.
Freebuff MCP lets Codex, Claude Code, plus other MCP apps work with Freebuff Desktop plus its command line app on your computer. It can find projects, read threads, send a request, show progress, read ordinary project files, plus stop work when the app asks.
MCP is a shared way AI apps connect to tools on your computer.
Your computer runs the bridge. Your Freebuff installation controls access to your projects. The bridge does not read process memory. It does not remove Freebuff approval steps. Text returned to an MCP app has common secret patterns masked. Pattern checks can miss unusual secrets. Do not treat them as a complete security boundary.
Start here
Node.js 22 or newer is required. Install Freebuff Desktop. The command line app works too. Sign in before connecting an MCP app.
npm install --global freebuff-mcp
freebuff-mcp doctorThe doctor report shows whether Desktop is found, whether it allows changes, whether the command line app is available, plus whether its terminal component works. A found app can still be signed out. A missing terminal component can block command line sessions. Check the report before setting up an MCP app.
Related MCP server: Local-MCP-Bridge
Connect an MCP app
Codex setup prints its settings entry.
freebuff-mcp install codexClaude Code setup prints its instructions.
freebuff-mcp install claudeThe automatic write option adds the entry to your app settings. It preserves other settings. It refuses to replace a different Freebuff entry.
What you can ask it to do
The bridge can find projects and threads, search visible thread metadata or one thread's messages, read thread messages in full or in pages, start a request, continue earlier work, show live progress, stop a turn, resume a paused thread, change model settings, inspect changed files, and read project files. Attachment metadata is available when the owning backend exposes it.
The tools are grouped around the work you can do:
Find projects and threads with
list_projects,list_threads,list_threads_page,search_threads, andget_active_work. Usesearch_threads_pagewhen a metadata search has many matches. Search one conversation withsearch_thread_messages. Read a thread withget_thread,get_thread_settings, orget_thread_messages. Useget_thread_messages_pagefor bounded results and continue with itsnextOffsetwhilehasMoreis true.Read files with
list_project_filesandget_project_file. The olderread_project_filename remains available. Thread attachment metadata is available throughlist_thread_attachments.Start or attach to a session with
create_thread. The olderstart_threadname remains available. Send a request withsend_messageand follow it withget_turnorwatch_turn, or userun_turnto wait for its result.Follow work with
get_thread_progress,watch_thread,get_thread_progress_summary, andwatch_active_threads. Review changed paths and Desktop diffs withget_changed_files,get_changes, andget_diff.Stop work with
stop_turnorstop_thread, resume withresume_thread, and request model or reasoning changes withset_modelandset_reasoning.get_freebuff_statusreports connection, authorization, and actions the bridge supports, including whether the selected backend can list attachment metadata. The olderfreebuff_statusname remains available.search_historyremains available as a compatibility name forsearch_threads.list_modelsremains available as a compatibility name forget_model_catalog_status. Current Freebuff backends do not provide a standalone model catalog, so useget_thread_settingsfor the model reported on a thread. Freebuff still controls which models your account can use.
The bridge keeps compatibility names for existing clients. New integrations should use get_freebuff_status, get_project_file, create_thread, search_threads, and get_model_catalog_status as the canonical names.
MCP tool definitions include parameter descriptions and explicit read, write, repeatability, and external-system hints. Agent-run tools are marked as potentially destructive because Freebuff may edit files or run commands. A backend may omit settings it cannot report; the settings tool lists those fields as unavailable instead of guessing. Project creation and thread deletion are not exposed because the supported Freebuff interfaces do not provide verified operations for them.
get_diff reports whether its paths came from a Desktop change summary, bridge progress events, or no available source. Event-derived paths may omit earlier changes; an unavailable source is reported instead of looking like an empty change list. A file-filtered request also says whether that path was found.
run_turn stays open while Freebuff works. It reports progress while the turn runs. When the MCP app cancels the request, the bridge asks the owning Freebuff backend to stop. A local cancel alone does not prove the work stopped.
Freebuff can ask you to approve a step. The turn stays marked as waiting. Resume checks the same thread. The bridge marks the turn complete only after Desktop confirms a finish. Use stop_turn to stop a waiting turn. Command line resume may not prove that the original work finished. The bridge keeps that turn open when its result is uncertain.
Progress arrives in pages. Each returned cursor points to the last event in that page. Use it to read the next page without skipping events. Page size is limited to keep replies manageable.
Local connection plus remote connection
The default connection uses standard input plus output. This works well when your MCP app runs on the same computer.
An optional remote web connection is available through Streamable HTTP.
freebuff-mcp serve-httpIt listens on 127.0.0.1 port 8788. Requests need the token in FREEBUFF_MCP_TOKEN. Remote binding also needs FREEBUFF_MCP_ALLOW_REMOTE=1. Remote use needs trusted HTTPS. A private network also works. Keep the access token private. The remote server still needs access to Freebuff on the computer where the bridge runs.
ACP is another tool connection format. This project's ACP support is experimental. Use MCP to do normal work.
When a connection fails
Run the doctor first. Desktop can be visible while change access remains unavailable. Restart Freebuff Desktop, reopen the project, then run the doctor again if its permission is missing. Check that the command line app is installed plus signed in if Desktop cannot accept changes. Managed command line sessions need the terminal component.
Security plus privacy
File reads stay inside the selected project. Credential files are denied. Binary content is denied. Reads stop at one megabyte. Common passwords, access tokens, authorization headers, URLs, plus private key text are masked before they reach the AI app. Fields named password, token, secret, API key are masked too. No text pattern can find every possible secret. Review sensitive project data before sharing it with a model.
Read the security notes plus the privacy notes before using the bridge with private work.
Project health
The figures above come from the local suite run on this source revision. They describe automated checks. They do not prove live compatibility with every Freebuff version. The Desktop plus command line acceptance steps are in the acceptance checklist.
Build from source
CI covers the maintained Node.js LTS lines 22, 24, and 26 on Windows, macOS, and Linux.
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm buildThe automated suite uses fake Desktop plus command line services. It checks protocol behavior, event paging, cancellation, redaction, setup, plus error handling. It cannot prove that a signed in installation works on your computer. Use the acceptance checklist to record that separately.
Learn more
Read the changelog to see release history. Read the license before you share changes to this project.
Available Tools
14 toolsfreebuff_statusBRead-only
Detect Freebuff and bridge capabilities.
Inputs: no named parameters.
get_active_workCRead-only
Read visible active work.
Inputs: threadId.
get_threadBRead-only
Read thread metadata.
Inputs: threadId (required).
get_thread_messagesARead-only
Read visible messages for a thread.
Inputs: threadId (required).
list_modelsARead-only
List models exposed by the installed bridge.
Inputs: no named parameters.
list_project_filesCRead-only
List safe project files.
Inputs: projectId (required), relative.
list_projectsARead-only
List discovered Freebuff projects.
Inputs: no named parameters.
list_threadsCRead-only
List Freebuff Desktop threads.
Inputs: projectId.
read_project_fileCRead-only
Read one safe project file.
Inputs: path (required), projectId (required).
resume_threadC
Resume a paused Freebuff thread.
Inputs: threadId (required).
send_messageA
Send a text prompt to an existing Freebuff thread.
Inputs: text (required), threadId (required).
set_modelC
Set the model for an existing thread when supported.
Inputs: model (required), threadId (required), harnessId.
set_reasoningC
Set the reasoning effort for an existing thread when supported.
Inputs: effort (required), threadId (required).
stop_threadB
Stop a running Freebuff turn.
Inputs: threadId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct resource/action: status, projects, threads, messages, active work, files, models, and thread controls are clearly separated. get_thread vs get_thread_messages and send_message vs resume_thread are differentiated by metadata/content and new-prompt vs resume semantics.
Most tools follow a verb_noun snake_case pattern (list_*, get_*, send_message, set_model), which is predictable. The main outlier is freebuff_status, which lacks a verb, and read_project_file introduces a minor verb variation versus get_*.
At 14 tools, the surface is well-scoped for a Freebuff bridge: discovery/status, project/thread inspection, file access, model listing, messaging, and turn control each have a place. No tool feels redundant or bloated.
The set covers the main inspect-and-interact workflow: list/read threads and files, send messages, stop/resume turns, and configure model/reasoning. Obvious gaps are thread/project creation/deletion and explicit per-thread model/reasoning read-back, though these may be intentionally outside the bridge's scope.
Maintenance
Related MCP Connectors
Read-only Remote MCP for externally grounded AI agent trust receipts.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Read-only MCP server exposing a user ORANO library to their own AI agent.
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides desktop AI clients with sandboxed, controlled read, write, search, and management access to user-selected local folders and projects over the Model Context Protocol.212MIT
- AlicenseAqualityBmaintenanceEnables MCP-compatible AI clients to securely access explicitly authorized local project files and run approved development commands with bounded execution and audit logging.1MIT
- AlicenseCqualityCmaintenanceEnables local MCP clients to securely use the court's digital systems—public process lookup, fee calculation, CNJ metadata queries, and the CAP1G chat—without exposing credentials to the MCP protocol.351MIT
- AlicenseNot gradedqualityCmaintenanceEnables authorized remote MCP clients to securely reach local Mac or Windows tools over OAuth, including shell commands, file read/write, background jobs, screenshots, UI control, and clipboard access. It can also expose configured Desktop MCP servers and optional Claude Code task delegation.MIT