Skip to main content
Glama
freebuff-mcp
by Praket7

Freebuff MCP

Freebuff MCP connects an MCP app to Freebuff on your computer

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 doctor

The 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 codex

Claude Code setup prints its instructions.

freebuff-mcp install claude

The 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, and get_active_work. Use search_threads_page when a metadata search has many matches. Search one conversation with search_thread_messages. Read a thread with get_thread, get_thread_settings, or get_thread_messages. Use get_thread_messages_page for bounded results and continue with its nextOffset while hasMore is true.

  • Read files with list_project_files and get_project_file. The older read_project_file name remains available. Thread attachment metadata is available through list_thread_attachments.

  • Start or attach to a session with create_thread. The older start_thread name remains available. Send a request with send_message and follow it with get_turn or watch_turn, or use run_turn to wait for its result.

  • Follow work with get_thread_progress, watch_thread, get_thread_progress_summary, and watch_active_threads. Review changed paths and Desktop diffs with get_changed_files, get_changes, and get_diff.

  • Stop work with stop_turn or stop_thread, resume with resume_thread, and request model or reasoning changes with set_model and set_reasoning. get_freebuff_status reports connection, authorization, and actions the bridge supports, including whether the selected backend can list attachment metadata. The older freebuff_status name remains available.

  • search_history remains available as a compatibility name for search_threads. list_models remains available as a compatibility name for get_model_catalog_status. Current Freebuff backends do not provide a standalone model catalog, so use get_thread_settings for 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-http

It 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

Automated project checks

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 build

The 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 tools
freebuff_statusB
Read-only

Detect Freebuff and bridge capabilities.

Inputs: no named parameters.

get_active_workC
Read-only

Read visible active work.

Inputs: threadId.

get_threadB
Read-only

Read thread metadata.

Inputs: threadId (required).

get_thread_messagesA
Read-only

Read visible messages for a thread.

Inputs: threadId (required).

list_modelsA
Read-only

List models exposed by the installed bridge.

Inputs: no named parameters.

list_project_filesC
Read-only

List safe project files.

Inputs: projectId (required), relative.

list_projectsA
Read-only

List discovered Freebuff projects.

Inputs: no named parameters.

list_threadsC
Read-only

List Freebuff Desktop threads.

Inputs: projectId.

read_project_fileC
Read-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

    B3.3/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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_*.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Provides desktop AI clients with sandboxed, controlled read, write, search, and management access to user-selected local folders and projects over the Model Context Protocol.
      2
      12
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables 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.
      35
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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