@mcpmarket/mcp-auto-install

An MCP server that lets LLMs discover, install, and manage other MCP servers through natural language. Backed by the official MCP Registry, with an npm-scope fallback for offline / outage scenarios.

What's new in v0.3.0

• Complete install plans: mai_install returns kind: package | remote | unsupported and reports requiredEnvVars with every registry hint (default, format, choices), requiredArguments for package arguments it could not fill, and requiredHeaders for remotes
• arguments input on mai_install (--arg name=value on the CLI) to fill package arguments, symmetric with env
• Remote servers resolve to a { type, url, headers } config instead of failing
• More package types: NuGet via dnx <id>@<version>, Cargo binaries by crate name; mcpb bundles are reported as unsupported instead of getting a bogus npx command
• Structured output: mai_install declares an outputSchema and returns the plan as structuredContent
• Tool annotations and titles: read-only tools carry readOnlyHint, config-writing tools carry destructiveHint

See CHANGELOG.md for the full release notes.

Installation

The most common usage is to register this package as an MCP server in your LLM client.

Claude Desktop / Cursor / Windsurf

Add to your client's MCP config:

{
  "mcpServers": {
    "mcp-auto-install": {
      "command": "npx",
      "args": ["-y", "@mcpmarket/mcp-auto-install"]
    }
  }
}

Restart the client. The 5 mai_* tools become available to the LLM.

Global install (optional, for CLI use)

pnpm add -g @mcpmarket/mcp-auto-install
# both `mai` and `mcp-auto-install` are now on your PATH

Usage as an MCP server

Once registered, ask the LLM in natural language. Example:

"Find me an MCP server for filesystem access, install the official one for Claude Desktop, and tell me what env vars I need to set."

The LLM will chain mai_search → mai_details → mai_install to complete the task.

Tool reference

| Tool | Purpose | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | mai_search | Search the registry by keyword. Returns name, description, version, supported package types. | | mai_details | Structured metadata for a server: env vars, arguments, transport, install command. | | mai_readme | Fetch the full README from GitHub. Use when you need usage examples or a tool list (mai_details is summary-only). | | mai_install | Build the install plan (launch command, or URL for remotes) and write it to all detected client config files. Accepts env and arguments; dryRun: true returns the plan as structuredContent instead of writing. | | mai_remove | Remove a server from all client config files. |

Usage as a CLI

The same operations are available as CLI commands using the mai binary:

mai search filesystem
mai info io.github.modelcontextprotocol/server-filesystem
mai readme io.github.modelcontextprotocol/server-filesystem
mai install io.github.modelcontextprotocol/server-filesystem --env API_KEY=xxx --arg root=/data
mai install io.github.modelcontextprotocol/server-filesystem --dry-run
mai remove io.github.modelcontextprotocol/server-filesystem
mai --help

mai with no arguments starts the MCP server (same as mai start). The legacy mcp-auto-install command is preserved as an alias.

Configuration

Client config locations

By default, mai_install / mai install writes to all detected client config files:

| Client | macOS | Windows | Linux | | -------------- | ----------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------- | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | %APPDATA%/Claude/claude_desktop_config.json | ~/.config/Claude/claude_desktop_config.json | | Cursor | ~/.cursor/mcp.json | %USERPROFILE%/.cursor/mcp.json | ~/.cursor/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | %USERPROFILE%/.codeium/windsurf/mcp_config.json | ~/.codeium/windsurf/mcp_config.json |

Set MCP_SETTINGS_PATH to override and target a single file.

Environment variables

| Variable | Default | Description | | -------------------- | -------------------------- | ----------------------------------------------------------------------------------------------- | | MCP_SETTINGS_PATH | (unset) | Override target config file. When set, only this file is written. | | MCP_REGISTRY_PATH | ~/.mcp/mcp-registry.json | Local cache file for registry data (1-hour TTL). | | MCP_PACKAGE_SCOPES | @modelcontextprotocol | Comma-separated npm scopes used by the npm-scope fallback when the Registry API is unreachable. |

Custom-config clients (dryRun)

Clients that manage their own MCP config (e.g. SQLite-backed CherryStudio) should call mai_install with dryRun: true. The tool returns the install plan as structuredContent (mirrored as JSON text in content) without touching any files; the client persists config to its own storage and collects whatever is still listed as required.

Request:

{
  "name": "mai_install",
  "arguments": {
    "serverName": "io.github.modelcontextprotocol/server-filesystem",
    "env": { "API_KEY": "xxx" },
    "arguments": { "root": "/data" },
    "dryRun": true
  }
}

structuredContent for a package:

{
  "serverName": "io.github.modelcontextprotocol/server-filesystem",
  "kind": "package",
  "registryType": "npm",
  "transport": { "type": "stdio" },
  "config": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
    "env": { "API_KEY": "xxx" }
  },
  "requiredEnvVars": [
    { "name": "WORKSPACE_ROOT", "description": "...", "isSecret": false, "format": "filepath" }
  ],
  "requiredArguments": []
}

structuredContent for a remote-only server:

{
  "serverName": "com.example/remote",
  "kind": "remote",
  "transport": { "type": "streamable-http" },
  "config": {
    "type": "streamable-http",
    "url": "https://mcp.example.com/mcp",
    "headers": { "X-App": "…" }
  },
  "requiredHeaders": [{ "name": "Authorization", "description": "...", "isSecret": true }]
}

kind: "unsupported" carries a reason (for example, a server that only ships an mcpb bundle).

Prerequisites

• Node.js >= 18.0.0
• An MCP-compatible client (Claude Desktop, Cursor, Windsurf, CherryStudio, ...)

Contributing

Issues and PRs welcome at github.com/CherryHQ/mcpmarket.

License

MIT