convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
ankitvg

Madari – Gerenciador CLI de MCP Servers

ankitvg/madari

Deploy, sincronização e gerenciamento centralizado de MCP servers

Ver no GitHub
InicialPluginScore · de 0 a 100

CLI em Go para instalar, registrar, sincronizar e gerenciar MCP servers locais em clientes de IA. Automatiza deploy, versionamento e agrupamento lógico de servidores via 'rings', com suporte a múltiplos clientes e escopos (projeto/usuário).

Instalação

$npx convez-ai ankitvg/madari

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 semanas
Versão
v0.2.2
Issues abertas
14
Contribuidores
1

Casos de uso

  • Instalar e registrar MCP servers em Claude e outros clientes de IA
  • Sincronizar configurações de servidores entre ambiente local e remoto
  • Gerenciar múltiplas instâncias MCP com 'rings' (conjuntos nomeados de capacidades)
  • Automatizar deploy de ferramentas customizadas em pipelines de desenvolvimento

Veredito

Ferramenta madura e bem-estruturada para quem opera infraestrutura MCP em escala. A abstração de 'rings' e suporte a escopos (projeto/user) diferencia-a de soluções ad-hoc; recomendado para times que sincronizam múltiplos clientes e precisam de rastreabilidade de configurações.

README

A tradução para o português deste README ainda está na fila.

madari (muh-DAA-ree)

Madari is a CLI to deploy MCP servers into your AI client setup with reliable install, registration, and sync.

Installation

Homebrew (recommended):

brew tap ankitvg/tap
brew install madari

Go:

go install github.com/ankitvg/madari/cmd/madari@latest

Commands

  • madari install <package> [options]
  • madari add <name> --command <cmd> --client <client>
  • madari list [--json]
  • madari remove <name>
  • madari enable <name>
  • madari disable <name>
  • madari sync <client> [--dry-run] [--config-path <path>] [--json] [--scope project|user]
  • madari ring create <name> --member <server> [--member ...] [--description <text>]
  • madari ring list [--json]
  • madari ring show <name> [--json]
  • madari ring attach <ring> <client> [--scope project|user] [--dry-run] [--config-path <path>]
  • madari ring detach <ring> <client> [--scope project|user] [--dry-run] [--config-path <path>]
  • madari ring delete <name>
  • madari ring render <name> --client <target>
  • madari ring status [--json]
  • madari clients
  • madari doctor [--client-config target=path ...] [--json]
  • madari status [--client-config target=path ...] [--json]
  • madari export [--file <path>]
  • madari import --file <path> [--apply]
  • madari help [command]
  • madari version

Notes:

  • install runs package-manager install (uv by default, or npm via --manager npm), auto-registers the server, and syncs to configured clients in one command.
  • install requires the selected package manager in PATH unless you use --skip-install and pass --command.
  • install --manager npm requires --command because npm package names can differ from executable names.
  • add resolves --command to an absolute executable path and stores that path in the manifest.
  • sync skips servers with missing/non-executable command paths and continues syncing others.
  • Manifests can mark secret env keys ([secret_env], or --secret-env on add/install); sync refuses to write their static values into the repo-scoped Claude Code .mcp.json — refused entries are reported with guidance (and scrubbed if previously materialized) while other servers sync normally. Use madari sync claude-code --scope user to materialize them into the user-scoped ~/.claude.json instead.
  • list shows the managed sources owning each synced entry (standalone today; - when not synced), and status summarizes managed entries per client.
  • list, status, doctor, sync --dry-run, ring list, ring show, and ring status accept --json for machine-readable output with a versioned schema; schemas and exit codes are documented in docs/cli-reference.md.
  • Rings are named capability sets of servers (madari ring …). Members reference registry entries by name — the server manifest stays the single source of truth for command, args, and env.
  • ring attach records reference-counted ownership (ring:<name> sources) and materializes eligible members; ring detach releases it, and an entry only leaves the client config when nothing owns it anymore. Overlapping rings and standalone+ring combinations resolve by refcount, in any order. Attaching onto an entry madari does not manage is refused — even when values match.
  • ring delete removes only unattached ring definitions. It refuses while any client scope still records ring:<name> ownership and prints scoped detach guidance; deletion never edits client configs or managed state.
  • ring render prints a self-contained MCP config to stdout for ephemeral use — claude --mcp-config <(madari ring render research --client claude-code) — mutating nothing; secret env values are never emitted. ring status shows attached rings and per-server ownership for every client and scope.
  • Supported sync clients: claude-desktop and claude-code.
  • Default sync config paths:
    • claude-desktop: platform-specific Claude Desktop config path.
    • claude-code: <current working directory>/.mcp.json.
  • install --config-path can only be used when exactly one sync target is selected.
  • export writes a versioned JSON snapshot of server and ring manifests for backup/sharing (stdout by default).
  • import is dry-run by default and only adds/updates listed servers and rings (--apply persists). Existing servers and rings absent from the snapshot are left unchanged; imported rings are not attached or synced.

Claude Code project config shape (.mcp.json):

{
  "mcpServers": {
    "stewreads": {
      "command": "/Users/me/.local/bin/stewreads-mcp",
      "args": ["--stdio"],
      "env": {
        "STEWREADS_CONFIG_PATH": "~/.config/stewreads/config.toml"
      }
    }
  }
}

Example:

madari install stewreads-mcp
madari install @modelcontextprotocol/server-sequential-thinking --manager npm --command mcp-server-sequential-thinking
madari add stewreads --command /Users/me/.local/bin/stewreads-mcp --client claude-desktop
madari add stewreads --command /Users/me/.local/bin/stewreads-mcp --client claude-code
madari list
madari status
madari sync claude-desktop --dry-run
madari sync claude-code --dry-run
madari export --file madari-snapshot.json
madari import --file madari-snapshot.json
madari import --file madari-snapshot.json --apply
madari doctor
madari help install
madari version

Rings — bundle servers into a capability set, attach it to a client, and spin it up ephemerally:

madari ring create research --member stewreads --member arxiv
madari ring attach research claude-code
madari ring status
claude --mcp-config <(madari ring render research --client claude-code)
madari ring detach research claude-code
madari ring delete research

Development

Build:

make build

Test:

go test ./...

Architecture

  • Reads registry state, writes client configs; no daemon or proxy
  • Only touches entries Madari registered; everything else keeps its JSON value, including fields and server shapes Madari does not model
  • Backup + atomic write on every sync; skips invalid entries rather than aborting
  • Reference-counted ring ownership: entries leave a client config only when nothing owns them
  • doctor and status for diagnostics, drift detection, and ring consistency
  • Supports uv and npm package manager installs, plus manual add for any runtime/framework
  • macOS, Linux, and Windows; supports Claude Desktop and Claude Code sync targets

Principles

  • Local-first and transparent
  • Human-readable config
  • Safe writes (backup + atomic replacement)
  • Explicit ownership of managed entries

Documentation

  • docs/architecture.md
  • docs/manifest-spec.md
  • docs/cli-reference.md
  • docs/troubleshooting.md

License

Apache License 2.0. See LICENSE and NOTICE.

Ver o original no GitHub

Bom para

Relacionados