<!-- SPDX-FileCopyrightText: 2026 FocusMCP contributors SPDX-License-Identifier: MIT -->

@focus-mcp/cli

Focus your AI agents on what matters. Measured savings: 65.3% on output tokens across all 69 bricks (details).

What

FocusMCP is an MCP (Model Context Protocol) orchestrator. Instead of giving your AI agent ALL your tools at once — polluting its context window — you compose bricks: atomic MCP modules that load on demand.

• 68+ official bricks covering files, code intel, git, shell, reasoning, search, and more
• One CLI, one MCP server, modular capabilities
• Works with Claude Code, Cursor, Codex, Gemini CLI, any MCP-compatible AI

Install

npm install -g @focus-mcp/cli

Or via the Claude Code native plugin:

Install for Claude Code

Option 1 — Two lines (works today)

/plugin marketplace add focus-mcp/cli
/plugin install focus-mcp@focus-mcp-cli

Option 2 — Manual MCP add

claude mcp add focus-mcp npx @focus-mcp/cli start

(Official single-liner /plugin install focus-mcp@claude-plugins-official coming once Anthropic accepts the submission.)

Requires Node.js ≥ 22.

Quick start

Add FocusMCP as an MCP server in your AI client config:

{
    "mcpServers": {
        "focus": {
            "command": "npx",
            "args": ["-y", "@focus-mcp/cli", "start"]
        }
    }
}

For Claude Code specifically, this is already wired via the native plugin above.

Then browse and manage bricks:

focus browse          # Interactive TUI — browse, search, install/uninstall bricks
focus search git      # Search the catalog for bricks matching "git"
focus add echo        # Install the "echo" brick
focus list            # Show all installed bricks
focus info echo       # Show details for a specific brick

Windows

FocusMCP supports Windows as of @focus-mcp/cli >= 2.3.1. Earlier versions may fail when installing or loading bricks because of Windows .cmd wrappers and path separator handling.

Requirements

• Windows 10/11
• Node.js >= 22
• npm available from PowerShell or Command Prompt
• @focus-mcp/cli >= 2.3.1

Install

npm install -g @focus-mcp/cli@latest
focus --version

Expected:

@focus-mcp/cli 2.3.1 or newer

Test

focus search cache
focus add cache
focus list

MCP client config on Windows

For Windows MCP clients, prefer launching through cmd.exe and the .cmd shim, especially when using nvm4w or when the client does not inherit your interactive shell PATH.

Generic MCP JSON:

{
    "mcpServers": {
        "focus": {
            "command": "C:\\\\Windows\\\\System32\\\\cmd.exe",
            "args": ["/d", "/c", "focus.cmd", "start"]
        }
    }
}

If your MCP client cannot find focus.cmd, use the full path:

{
    "mcpServers": {
        "focus": {
            "command": "C:\\\\Windows\\\\System32\\\\cmd.exe",
            "args": ["/d", "/c", "C:\\\\nvm4w\\\\nodejs\\\\focus.cmd", "start"],
            "env": {
                "PATH": "C:\\\\nvm4w\\\\nodejs;C:\\\\Users\\\\<user>\\\\AppData\\\\Roaming\\\\npm;C:\\\\Windows\\\\System32;C:\\\\Windows"
            }
        }
    }
}

Codex on Windows

Add this to %USERPROFILE%\.codex\config.toml:

[mcp_servers.focus]
command = "C:\\\\Windows\\\\System32\\\\cmd.exe"
args = ["/d", "/c", "C:\\\\nvm4w\\\\nodejs\\\\focus.cmd", "start"]
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.focus.env]
PATH = "C:\\\\nvm4w\\\\nodejs;C:\\\\Users\\\\<user>\\\\AppData\\\\Roaming\\\\npm;C:\\\\Windows\\\\System32;C:\\\\Windows"
FOCUS_NO_UPDATE_NOTIFY = "1"

Replace <user> and the Node path if you do not use nvm4w.

Troubleshooting

If brick installation fails with:

spawn npm ENOENT

update FocusMCP:

npm install -g @focus-mcp/cli@latest

If brick loading fails with:

escapes bricksDir

make sure focus --version reports 2.3.1 or newer.

Commands

Command	Description
focus list	List installed bricks (reads ~/.focus/center.json)
focus info <name>	Show details for a brick (version, catalog, config)
focus start	Launch FocusMCP as an MCP server over stdio
focus add <name>	Install a brick from the catalog
focus remove <name>	Uninstall a brick
focus search <query>	Search the catalog
focus catalog	Show and manage catalog sources
focus browse	Interactive TUI browser (see below)

Interactive TUI — focus browse

focus browse opens a full-screen terminal interface to explore, search, and manage bricks without leaving your terminal.

┌─ Bricks (68) ────────────────┬─ echo ───────────────────────────────────┐
│ > echo              ✓        │                                          │
│   indexer                    │  A simple echo brick for testing.        │
│   shell                      │                                          │
│   git-log                    │  Version   ^1.0.0                        │
│   web-search                 │  Source    @focus-mcp/echo               │
│   …                          │  Status    installed                     │
│                              │                                          │
│  / search  i install         │  [i] Install   [u] Uninstall             │
│  ↑↓ nav    Enter open        │  [?] Help                                │
└──────────────────────────────┴──────────────────────────────────────────┘

Keybindings:

Key	Action
↑ / ↓	Navigate the brick list
Enter	Open brick details
/	Search / filter
i	Install selected brick
u	Uninstall selected brick
?	Toggle help overlay
q / Esc	Quit

Filtering exposed tools

By default, focus start exposes all tools from every loaded brick plus the focus management tools (focus_*). You can hide specific tools using a blacklist.

Per-launch: --hide

# Hide a single tool
focus start --hide=sym_get

# Hide an entire family with a glob
focus start --hide="focus_*"

# Hide multiple patterns (comma-separated)
focus start --hide="sym_get,ts_cleanup"

Patterns support a trailing * glob (focus_* matches focus_install, focus_list, etc.). Exact names are also accepted.

Note: focus_tools is always visible regardless of the hidden list, so you can always manage tool visibility from within your AI client.

Persistent config: ~/.focus/config.json

Add a tools section to persist filters across sessions:

{
    "tools": {
        "hidden": ["sym_get", "fo_delete"],
        "alwaysLoad": ["ts_index"]
    }
}

CLI flags override the config file. If neither is set, all tools are exposed (default).

Add --pin=<patterns> to mark tools as always-loaded (surfaced as _meta.anthropic/alwaysLoad: true in MCP responses):

focus start --pin="ts_index,sym_find"

Manage from the terminal: focus tools:

focus tools:list               # show current hidden + alwaysLoad lists
focus tools:hide sym_get       # add sym_get to the hidden list
focus tools:hide "focus_*"     # hide an entire family (glob)
focus tools:show sym_get       # remove sym_get from the hidden list
focus tools:pin ts_index       # mark ts_index as alwaysLoad
focus tools:unpin ts_index     # remove ts_index from alwaysLoad
focus tools:clear              # reset both lists

# Legacy aliases (permanent, no deprecation):
focus filter list
focus filter hide sym_get

Changes are written to ~/.focus/config.json and take effect on the next focus start.

From your AI client: focus_tools MCP tool

The focus_tools MCP tool lets your AI agent manage tool visibility directly:

focus_tools action=hide   pattern=sym_get
focus_tools action=show   pattern=sym_get
focus_tools action=pin    pattern=ts_index
focus_tools action=unpin  pattern=ts_index
focus_tools action=list
focus_tools action=clear

Restart focus start (or reload your MCP client) to apply changes.

Architecture

AI client (Claude Code, Cursor, Codex, …)
       │ stdio (JSON-RPC / MCP)
       ▼
@focus-mcp/cli  (this package)
  ├─ @modelcontextprotocol/sdk  StdioServerTransport
  ├─ @focus-mcp/core            Registry + EventBus + Router + brick loader
  └─ ~/.focus/center.json       user brick declarations

Bricks are atomic MCP modules. Each brick exposes exactly one domain of tools to the AI agent. You declare which bricks you want in ~/.focus/center.json; FocusMCP loads them on demand when focus start is called.

Why not give the agent all tools at once? Because a 200k-token context window filled with hundreds of tool descriptions leaves very little room for actual work. FocusMCP keeps the agent's context lean — ~2k tokens for the orchestrator itself — and loads domain-specific tools only when needed.

For AI agents

If you are an AI agent (Claude Code, Cursor, Cline, Codex, etc.) and want to bootstrap on a new project using FocusMCP, read the Agent Bootstrap Guide. It covers stack detection, brick search and install, tool pinning, and common workflows — optimized for LLM consumption.

Links

• Marketplace: https://github.com/focus-mcp/marketplace
• Core library: https://github.com/focus-mcp/core
• Official catalog: https://raw.githubusercontent.com/focus-mcp/marketplace/main/publish/catalog.json
• Website: https://focusmcp.dev

AI-assisted development

FocusMCP was built with heavy Claude Code assistance — its architecture, implementation, docs, and tests have all been co-authored with AI. We embrace this openly because:

1. Transparency matters — we'd rather disclose it than pretend otherwise
2. AI tooling is the context — we're building tools for AI agents, it makes sense to use them
3. Quality over origin — what matters is that the code is tested, reviewed, and working

Your AI-assisted contributions are welcome. We don't require you to hide the fact that Claude, Copilot, Cursor, or any other tool helped you. What we do expect:

• Tests pass, code is typed, lint is green
• You've read the diff and understand what the PR does
• Conventional Commits, clear PR description
• You can explain your design choices during review

See CONTRIBUTING.md for the full guidelines.

License

MIT