Toolmux
fiam/toolmux
Integração segura de SaaS e MCP servers locais com credenciais cifradas
Ver no GitHubMCP server que conecta fluxos de terminal e agentes locais a ferramentas SaaS e servidores MCP remotos com gerenciamento de credenciais locais e verificações de política. Funciona como uma camada de abstração única para integrar Slack, Google Drive, GitHub e outras 25+ ferramentas remotas sem expor tokens nos prompts.
Instalação
npx convez-ai fiam/toolmux1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Conectar agentes de IA (Claude, Codex) a múltiplas ferramentas SaaS sem copiar tokens
- Automatizar workflows com Slack, Google Drive, GitHub e outros serviços via CLI
- Orquestrar servidores MCP remotos com políticas de acesso e modo read-only
Veredito

Solução robusta e bem pensada para o problema real de integração segura de credenciais em agentes locais. Abordagem inteligente de custódia de credenciais via credential store do SO e políticas granulares. Ainda em estágio inicial, mas com suporte sólido para Slack, Google e 25+ provedores via catálogo MCP.
README
A tradução para o português deste README ainda está na fila.
Toolmux
Website: toolmux.com
Toolmux connects services to your local agents and gives you the same tools as a normal CLI. Register Slack, Google, or a remote MCP server once, configure your agent once, then ask the agent to use those tools without copying tokens into prompts.
Toolmux is built around four ideas:
- One command surface for people, scripts, and agents.
- Local credential custody through the operating system credential store.
- Tool policy and
--read-onlychecks before tool credentials are loaded. - Workflows that turn repeatable prompts into commands.
Toolmux is early software. Today it is most useful for Slack, Google Drive, remote MCP toolboxes, and local agent setup for Codex and Claude Code.
Supported Today
| Area | What is supported |
|---|---|
| Native toolboxes | Slack, Google Drive, Google Docs |
| Remote MCP catalog | Hosted Streamable HTTP MCP servers listed by toolmux list --mcp |
| Custom remote MCP | Any compatible Streamable HTTP MCP server URL |
| Agents | Codex, Claude Code |
| Workflow templates | slack-recap |
Use the CLI for the live list in your installed version:
toolmux --help
toolmux list
toolmux list --mcp
toolmux list --internal
toolmux workflow templates
toolmux list lists every built-in toolbox and includes a Type column so
you can distinguish remote MCP toolboxes from internal Toolmux toolboxes.
toolmux ls is a shortcut for the same command.
Remote MCP catalog entries are hosted endpoints that can be added and
authenticated through the server's own OAuth flow without creating your own
OAuth app first.
Built-in remote MCP entries currently include:
airtable asana atlassian cloudflare datadog
excalidraw figma gainsight github grafana
granola incident-io linear miro neon
notion pagerduty pagerduty-eu posthog sentry
stripe supabase vercel zoom zoominfo
Install
With Homebrew:
brew install --cask fiam/tap/toolmux
toolmux version
Release archives for macOS, Linux, and Windows are available from GitHub Releases. macOS release binaries are Developer ID-signed and notarized.
Quick Start
Start by seeing what Toolmux can connect:
toolmux list
toolmux list --mcp
Add Slack when you are ready to connect a real workspace:
toolmux add slack --auth broker
toolmux status slack
Configure your local agent to see Toolmux tools over MCP:
toolmux mcp configure
With no agent argument, Toolmux detects installed supported agents and opens an interactive selector. For scripts, name the agents explicitly:
toolmux mcp configure codex claude
Now ask your agent to use Toolmux, for example:
Use Slack through Toolmux to find the latest messages about the release plan.
Or run the built-in Slack recap workflow:
toolmux workflow init slack-recap --template slack-recap
toolmux workflow config set default-agent codex
toolmux workflow run slack-recap --input since=yesterday
If the Slack recap workflow has no delivery_channel input, it asks the agent
to send the recap to you by opening a Slack DM first and posting to that DM
channel.
Slack
Slack is a native Toolmux toolbox under the registered toolbox name, usually
toolmux slack. Native toolbox commands and MCP tools are shown when the
toolbox is registered in config. The registered name is also the credential
account identity, so multiple Slack workspaces can be added with distinct
names:
toolmux add slack --name slack-work --auth broker
toolmux add slack --name slack-personal --auth broker
Common setup options:
# Hosted Toolmux broker. This is the simplest OAuth path.
toolmux add slack --auth broker
# Explicit token and cookie values from environment variables.
toolmux add slack --token-env SLACK_TOKEN --cookie-env SLACK_COOKIE
# Your own Slack OAuth app with a local loopback callback.
toolmux add slack \
--auth oauth \
--client-id "$SLACK_CLIENT_ID" \
--client-secret-env SLACK_CLIENT_SECRET
# Explicit browser-session setup for a workspace subdomain.
toolmux add slack --workspace acme
--workspace is the Slack workspace subdomain, such as acme from
https://acme.slack.com. Browser-session setup only runs when you explicitly
request it with --workspace or --from-browser.
Useful Slack commands:
toolmux slack auth_test
toolmux slack channels_list --channel_types public_channel,private_channel
toolmux slack users_conversations --limit 20
toolmux slack experimental_conversations_list --query build
toolmux slack conversations_history --channel_id C123456 --limit 50
toolmux slack conversations_search_messages --search_query "from:@alice roadmap"
toolmux slack conversations_open --user_id U123456
toolmux slack conversations_add_message --channel_id C123456 --text "Build is green" --dry-run
toolmux slack conversations_add_message --channel_id C123456 --text "Build is green"
toolmux status slack
toolmux remove slack
Supported native Slack tool names:
- Auth:
auth_test - Channels and history:
channels_list,conversations_history,conversations_replies,conversations_search_messages,conversations_unreads,conversations_mark,users_conversations,experimental_conversations_list - Messages and DMs:
conversations_open,conversations_add_message - Files, reactions, users:
attachment_get_data,reactions_add,reactions_remove,users_search - User groups:
usergroups_list,usergroups_me,usergroups_create,usergroups_update,usergroups_users_update
In Enterprise/Grid workspaces, Slack may restrict workspace-wide
channels_list. Try users_conversations to list conversations the
authenticated user is a member of; this documented Slack API method can still
be restricted by workspace policy. experimental_conversations_list is a
read-only Slack web-session fallback for browser-session auth and is explicitly
prefixed as experimental because it uses an undocumented Slack web app endpoint.
Run toolmux slack --help for the command list and per-tool flags.
Google is a native Toolmux toolbox focused on Google Drive and Google Docs.
Google uses brokered OAuth through toolmuxd and stores one local Google OAuth
bundle per registered toolbox name in the OS credential store. The default and
only supported scope is the
non-sensitive drive.file scope, which lets Toolmux create files and access
files the user explicitly opens for the app. Docs read and write commands use
the same per-file grant.
Native Google commands and MCP tools are shown when the toolbox is registered
in config. The registered name is also the credential account identity:
toolmux add google --name google-work
toolmux add google --name google-personal
toolmux google docs get 1abc...
toolmux google docs find-structure 1abc... --kind heading
toolmux google docs export 1abc... --format markdown
toolmux google docs append 1abc... --text "Status update\n"
toolmux google docs replace-all-text 1abc... --text "old" --replace-text "new"
toolmux google docs style-ranges 1abc... --paragraph-style-type HEADING_2 \
--foreground-color "#336699"
toolmux google docs insert-table 1abc... --rows 3 --columns 2
toolmux google docs insert-image 1abc... --upload-file ./diagram.png \
--mime-type image/png --make-public
toolmux google docs insert-image 1abc... --content-base64 "$PNG_BASE64" \
--name diagram.png --mime-type image/png --make-public
toolmux google docs batch-update 1abc... --json @requests.json
toolmux google drive selected add
toolmux google drive selected list
toolmux google drive files copy 1abc... --name "Working copy" \
--target-mime-type application/vnd.google-apps.document
toolmux google drive files upload ./diagram.png --mime-type image/png --make-public
toolmux google drive files upload --content-base64 "$DOCX_BASE64" \
--name report.docx \
--mime-type application/vnd.openxmlformats-officedocument.wordprocessingml.document \
--target-mime-type application/vnd.google-apps.document
toolmux google drive files update 1abc... --name "Renamed file"
toolmux google drive files update 1abc... ./report.docx \
--mime-type application/vnd.openxmlformats-officedocument.wordprocessingml.document \
--target-mime-type application/vnd.google-apps.document
toolmux google drive files trash 1abc...
toolmux google drive selected remove 1abc...
toolmux google drive pick
toolmux google drive available
toolmux google drive search --query "mimeType='application/vnd.google-apps.document'"
toolmux google drive get --file-id 1abc...
toolmux status google
For normal file access, start with toolmux google drive selected add. It opens
the brokered Google Picker flow, saves selected file IDs locally, and stores
the OAuth token. Run toolmux add google only when you want Drive API access
before selecting files.
Default scope:
https://www.googleapis.com/auth/drive.file
With drive.file, Drive search is limited to files created by Toolmux or files
the user explicitly opened/shared with the Toolmux Google app. Drive-wide
discovery requires broader Drive scopes that Toolmux does not request.
Google Docs body reads and edits have the same per-file boundary: select or
open the document for Toolmux first, then use toolmux google docs get,
find-structure, export, append, replace-all-text, style-ranges,
insert-table, insert-image, or batch-update with the document ID or Docs
URL. find-structure returns Google Docs UTF-16 indexes for targeted edits.
batch-update accepts a full Docs API batchUpdate object, a requests array, or
@path; use --required-revision-id when an edit should only apply to a known
revision.
toolmux google drive selected add and toolmux google drive pick create a
short-lived Picker session in toolmuxd, open Google Picker in the browser,
and poll the broker until Google returns selected file IDs.
toolmux google drive selected add saves the selected file IDs locally for later
reference, while toolmux google drive pick returns Picker output without
saving it. toolmux google drive files copy accepts a raw file ID or a
Docs/Drive URL and copies an accessible file into My Drive, defaulting the
destination parent to root. The --target-mime-type flag requests Google
Workspace conversion during copy, such as converting a DOCX to native Google
Docs with application/vnd.google-apps.document. toolmux google drive files upload uploads content with Drive files.create; pass either a local path or
--content-base64 for MCP callers that do not share the CLI filesystem. Use
--make-public only when the file must be readable by anyone with the link,
such as when using a Drive-hosted image with Docs insert-image. The files update command uses Drive files.update to rename an accessible file, change
its trash state, or replace content with --upload-file, --content-base64,
or a second positional path. The --target-mime-type flag also requests
conversion during upload or content-replacing update. The files trash command
is a convenience command that moves an accessible file to Drive trash. With
drive.file, shared source files must be selected through Picker before Toolmux
can copy or update them. Removing a saved file only removes it from Toolmux's
local list; users can revoke app grants from their Google account when they need
Google to forget that per-file app access.
Toolmux uses one Picker path: a short-lived brokered Google Picker session
through toolmuxd. The CLI does not expose a local Picker fallback or a Picker
API key.
MCP Toolboxes
Toolmux can import MCP servers, cache their tool definitions, and expose them in two places:
- CLI commands under the registered toolbox name.
- Proxied MCP tools from
toolmux mcp serve.
Add from the built-in catalog:
toolmux list
toolmux add notion
toolmux mcp auth login notion
toolmux mcp sync notion
toolmux notion
Register a custom MCP endpoint:
toolmux add https://mcp.linear.app/mcp --name linear-work --no-sync
toolmux mcp auth login linear-work
toolmux mcp sync linear-work
toolmux linear-work
Register a command-backed MCP server over stdio:
toolmux add -- npx -y @upstash/context7-mcp
toolmux add -- docker run -i --rm browser-tools-mcp
Toolmux infers stdio MCP commands when the input is not a URL, built-in
catalog entry, or native toolbox. Use --name to override the derived command
namespace, and use --stdio only when the first command word would otherwise
match a built-in catalog entry or native toolbox. The -- separator is needed
when command arguments use dash-prefixed flags, so those flags are passed to
the command instead of Toolmux.
The registered name becomes the CLI namespace. A server named linear-work
exposes commands as toolmux linear-work <tool-name> and MCP tools as
linear-work.<tool-name>.
For repeated non-secret arguments, configure defaults:
toolmux mcp defaults set atlassian cloudId <cloud-id>
toolmux mcp defaults ls atlassian
Show registered toolboxes and cached tools:
toolmux status
toolmux mcp ls
toolmux mcp ls -R
toolmux mcp show linear-work
Inspect schemas and call tools:
toolmux mcp ls linear-work
toolmux mcp schema linear-work <tool>
toolmux linear-work <tool> --json '{"key":"value"}'
Use --json for tool inputs that cannot be represented as flags.
Agents
Toolmux serves MCP over stdio:
toolmux mcp serve
Most users should configure an agent instead of running mcp serve manually:
toolmux mcp configure
toolmux mcp configure codex
toolmux mcp configure claude --scope project
Supported agent names:
| Agent | Names |
|---|---|
| Codex | codex |
| Claude Code | claude, claude-code |
Configure additional agents through workflows.agents in
~/.toolmux/config.yaml or .toolmux/config.yaml, mapping a name to a command
and arguments.
For non-interactive setup and teardown:
toolmux mcp enable codex claude
toolmux mcp disable claude
Limit which tools an agent can see with MCP profiles:
toolmux mcp profile set readonly \
--tool 'grafana.*' \
--exclude-tool '*.send'
toolmux mcp profile default readonly
toolmux mcp configure codex --mcp-profile readonly --read-only
Workflows
Workflows are YAML files that render a Go text/template prompt and run a
local agent command.
Global workflows live in:
~/.toolmux/workflows
Project workflows live in:
.toolmux/workflows
List templates and create a workflow:
toolmux workflow templates
toolmux workflow init slack-recap --template slack-recap
Template names are loaded from this repository on GitHub. You can also use a GitHub template path or a direct YAML URL:
toolmux workflow init team-recap \
--template github:acme/workflows/slack-recap.yaml@main
toolmux workflow init custom \
--template https://example.com/workflow.yaml
Render a workflow before running it:
toolmux workflow render slack-recap --input since="yesterday 18:00"
Run with an explicit agent:
toolmux workflow run slack-recap \
--agent "codex --yolo" \
--input since="yesterday 18:00"
Set the default workflow agent:
toolmux workflow config set default-agent codex
In an interactive terminal, omit the value to select from detected agents:
toolmux workflow config set default-agent
Workflows can declare required toolboxes such as internal:slack,
catalog:linear, or a remote MCP URL. Missing requirements are added
automatically during workflow init and workflow run unless --no-setup is
passed.
If a workflow command or agent definition contains {{ .prompt }}, Toolmux
substitutes the rendered prompt there. Otherwise it appends the prompt as the
final argument.
Output
Human output is the default. In an interactive terminal, Toolmux can use tables, color, Markdown rendering, links, pagers, progress spinners, browser opens, and selectors.
Use structured output for scripts and agents:
toolmux --output json mcp ls -R
toolmux --output yaml list
JSON and YAML output are stable and undecorated: no ANSI escapes, prompts, spinners, pagers, or browser side effects.
Common global flags:
--output table|json|yaml
--color auto|always|never
--pager auto|always|never
--profile <name>
--policy <path>
--read-only
--mcp-tool-call-timeout <duration>
MCP toolbox calls wait up to 60s of response inactivity by default. Use
--mcp-tool-call-timeout, for example --mcp-tool-call-timeout 2m, when a
proxied MCP tool needs more time to return a tools/call response.
Safety
Toolmux stores non-secret config in:
~/.toolmux/config.yaml
Project config lives in:
.toolmux/config.yaml
Registered toolbox definitions, MCP server details, and cached tool metadata
are non-secret config. Native and remote toolboxes are stored under the
top-level toolboxes key; the map key is the registered command namespace and
the credential account identity.
Provider tokens, OAuth tokens, refresh tokens, bearer tokens, auth codes,
client secrets, and Slack token-cookie credentials are stored only in the OS
credential store or transient process memory.
Inspect and create config files with:
toolmux config paths
toolmux config show
toolmux config init --global
toolmux config init --project
toolmux config edit --global
toolmux config show prints the merged effective config by default. Use
--global or --project to print only one config file.
Use --read-only to block tool calls with local or remote write effects before
tool credentials are read:
toolmux --read-only google drive available
toolmux --read-only slack conversations_add_message \
--channel_id C123456 \
--text "This will be blocked"
Use local policy files for project guardrails around tool execution:
toolmux policy init
toolmux policy catalog
toolmux policy check --command "google drive available"
Policy discovery order:
--policy <path>TOOLMUX_POLICY=<path>.toolmux/policy.yamlin the current directory or a parent directory- No policy file, which allows local usage by default
Policy files are local guardrails for projects and automation. They are not a security boundary against a user who controls the machine or working directory.
Self-Hosting
Toolmux uses the hosted OAuth broker at https://api.toolmux.com by default
for native provider flows that require confidential client secrets.
To self-host the broker, point the CLI at your own toolmuxd:
export TOOLMUX_TOOLMUXD_URL=https://auth.example.com
Google Drive uses the broker by default. For self-hosting, create a Google web
OAuth client, enable the Drive and Picker APIs, configure the Google variables
on toolmuxd, and point the CLI at that broker with TOOLMUX_TOOLMUXD_URL.
Self-hosting instructions are in docs/SELF_HOSTING.md.
Help
toolmux --help
toolmux <toolbox> --help
toolmux mcp --help
toolmux workflow --help
toolmux doctor
For developer setup, tests, architecture notes, and release workflow, see CONTRIBUTING.md.