# The Smithery CLI installs MCP servers and calls their tools from a terminal

> smithery is the command line client for the Smithery registry, a TypeScript package published to npm that searches for MCP servers, adds them as connections, lists and calls the tools they expose, installs agent skills, handles OAuth and service tokens, and publishes servers or MCP bundles. It is a thin client over a hosted service, and it requires Node.js 20.

**arcadeai-labs/smithery-cli** — Install, manage and develop MCP servers and skills for agents

- Repository: https://github.com/arcadeai-labs/smithery-cli
- Website: https://smithery.ai
- Stars: 847 · Forks: 98
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/arcadeai-labs-smithery-cli

## A registry client, not an MCP runtime

The Smithery CLI connects your agents to thousands of skills and MCP servers directly from the command line, and the README's first instruction is to run npx skills add smithery/cli to get started. The package description in the manifest puts it more plainly: it is an NPX command to install and list Model Context Protocols from Smithery.

So the division of labour is this. The CLI is the client side of a hosted registry. It searches that registry, records the connections you choose, and gives you a terminal surface for the tools those servers expose. It does not host the servers, and it is not the thing your agent talks to at runtime.

That framing explains the shape of the command set. There is a group for MCP servers, a group for the tools behind those servers, a group for skills, a group for authentication, a group for namespaces, and a group for publishing. Everything is oriented around the registry rather than around a local configuration file.

The project is the work of arcadeai-labs, with the code hosted under the smithery-ai organisation, and the homepage is smithery.ai. It is written in TypeScript, published to npm as smithery, and licensed under AGPL-3.0.

The last push to the default branch was on 2026-05-31, and the release history is quick: v1.1.1 on 2026-05-22, v1.1.2 on 2026-05-29 and v1.2.0 on 2026-05-31.

## Installing the CLI and the skills package

The global install is one command:

```bash
npm install -g smithery@latest
```

and the README states the requirement of Node.js 20 or newer. The alternative, for people who would rather not install anything permanently, is the npx route the README opens with, npx skills add smithery/cli, which is the upstream skills installer pulling the CLI from the Smithery organisation.

There is a second, separate thing called skills, and the distinction matters. The Skills Registry is browsed through the CLI, but the installation is delegated to the upstream installer:

```bash
npx skills add <skill>   # e.g. npx skills add smithery-ai/cli
```

So the CLI is the catalogue and the manager, while the actual skill installation is done by another tool. That is a reasonable division, since skills are installed into an agent's configuration, and it means the CLI does not have to own the layout of every agent's skills directory.

For development, the README gives the clone and build steps:

```bash
git clone https://github.com/smithery-ai/cli
cd cli && pnpm install && pnpm run build
npx . --help
```

The build output is dist/index.js, which is both the main entry and the binary the package exposes as smithery, so a global install puts a smithery command on your path.

## The command groups and what each one is for

The command surface is organised by noun, and each group is small enough to read in one screen.

The MCP group manages connections to servers:

```bash
smithery mcp search [term]              # Search the Smithery registry
smithery mcp add <url>                  # Add an MCP server connection
smithery mcp list                       # List your connections
smithery mcp remove <ids...>            # Remove connections
```

The tool group works with what those servers expose, and it is the part that makes the CLI useful in a script, because it can list, search, describe and call:

```bash
smithery tool list [connection]        # List tools from your connected MCP servers
smithery tool find [query]             # Search tools by name or intent
smithery tool get <connection> <tool>  # Show full details for one tool
smithery tool call <connection> <tool> [args]  # Call a tool
```

The auth group is where the registry identity lives:

```bash
smithery auth login                     # Login with Smithery (OAuth)
smithery auth logout                    # Log out
smithery auth whoami                    # Check current user
smithery auth token                     # Mint a service token
smithery auth token --policy '<json>'   # Mint a restricted token
```

And namespaces, which are the organisational boundary for a registry account:

```bash
smithery namespace list                 # List your namespaces
smithery namespace use <name>           # Set current namespace
```

The pattern in all of them is the same: list something, select something, then act on it, with the current namespace deciding which account the actions apply to.

## Finding and calling a tool without leaving the shell

The examples section walks through a realistic sequence, and it is the clearest description of the intended workflow.

You search the registry for a server, then add it as a connection with an identifier:

```bash
smithery mcp search "github"
smithery mcp add github --id github
```

Then you look for the tool you want by intent rather than by exact name, which is the detail that matters when you are working with a server that exposes dozens of tools:

```bash
smithery tool find "create issue"
smithery tool call github create_issue '{"title":"Bug fix","body":"..."}'
```

The call takes the connection, the tool name and a JSON argument string. That shape is what makes the CLI scriptable: the output of a search can be piped, the tool name and arguments can be assembled by a shell script, and the whole thing runs in CI without a browser or an agent in the loop.

The skills side has a parallel form, including flags for machine consumption:

```bash
smithery skill search "frontend" --json --page 2
smithery skill add anthropics/frontend-design --agent claude-code
```

The --json and --page flags on the search command, and the --agent flag on the install command, show that the tool is being designed for agents as much as for people.

## Publishing a URL or a bundle

The publish commands are the other half of the story, and they come in two forms:

```bash
smithery mcp publish <url> -n <org/server>          # Publish an MCP server URL
smithery mcp publish <bundle.mcpb> -n <org/server>  # Publish an MCP bundle
```

The first publishes a running server by URL, the second publishes a bundle file with the .mcpb extension. The -n flag is the namespace and server name, so a server is published as an organisation and a name rather than as a bare URL.

The repository shows where the bundle format comes from. The development dependencies include @anthropic-ai/mcpb alongside the Model Context Protocol SDK and the Smithery API and SDK packages, so the .mcpb artefact is a defined bundle format rather than a zip the CLI invented.

For someone evaluating the tool, the split between publishing a URL and publishing a bundle is the meaningful design decision. A URL is a live server that somebody else runs, and it keeps running after you publish it. A bundle is the packaged form of a server, and it is what you publish when the server is not always up.

Both routes end at the same place, the registry, and both need a namespace and a name, so a published server is a registry entry with an identity rather than a link you keep in a notes file.

## The build pipeline behind the published package

The package manifest describes a fairly conventional TypeScript project, and the details say something about how the team works.

The build is tsc followed by a node build.mjs step and a chmod on dist/index.js, so the compiler and a bundler both run. The package manager is pnpm at 10.27.0, and the onlyBuiltDependencies list names the packages allowed to run install scripts, which is @biomejs/biome, esbuild, keytar, @smithery/api and workerd. keytar is the one to note: it is the native library that stores credentials in the operating system keychain, which is why it needs to be allowed to build.

The scripts show the quality gates. Tests run with vitest, and the test:list, test:install, test:installed and test:uninstall scripts run the CLI itself through tsx, so the command surface is exercised as a test rather than only unit tested. Linting and formatting are Biome, with biome check and a check --write --unsafe variant, type checking is tsc --noEmit, and knip is there to find unused files and dependencies.

Versioning is handled by release-please, with a .release-please-manifest.json and a release-please-config.json in the repository, plus .githooks wired up through the prepare script with git config core.hooksPath. There is also an AGENTS.md and a CLAUDE.md at the top level, and a skills directory in the repository, which is where the CLI keeps its own agent instructions.

## Where the boundaries are

Three limits are worth naming before you build a pipeline on this.

The first is the hosted dependency. The registry, the skill catalogue and the OAuth login all live at smithery.ai. A server that must run entirely on your own infrastructure, or that must be discoverable by a client that cannot reach the registry, is outside what this CLI does. The alternative there is to run the MCP server yourself and point an agent at it directly, without a registry in the middle, which means you lose the search, the connection records and the tool discovery that make the CLI pleasant, and you gain independence from a service you do not control.

The second is licensing. AGPL-3.0 is a demanding choice for a command line tool, and it is the one to think about if you intend to ship the CLI inside a closed product, because the network use clause of the AGPL is written for exactly that case. The repository also carries a LICENSE file and the usual governance files.

The third is that a connection is not a configuration. smithery mcp add records a connection in the registry, and your agent still has to be told to use that server, through whatever configuration format your agent uses. The CLI is the front half of the setup, not the whole of it.

One more practical detail: the postinstall script runs node scripts/postinstall.js, so a global install executes code at install time, which is normal for this kind of package and worth remembering for a locked down environment.

## Conclusion

Adopt smithery when you want to discover MCP servers from a registry, wire them into an agent, and call their tools from a script, and you are happy to depend on a hosted service. Do not adopt it for servers that must run entirely on your own infrastructure, and read the AGPL-3.0 terms before shipping it inside a closed product. Before you commit, check that a service token with a policy is enough for your use rather than a full login, because the auth commands distinguish a plain token from one restricted with a policy, and remember that a connection added with smithery mcp add is a registry entry that your agent configuration still has to reference.

## FAQ

### How do I install the Smithery CLI?

Run npm install -g smithery@latest, which requires Node.js 20 or newer, or use the npx route the README opens with, npx skills add smithery/cli. The package exposes a smithery command backed by dist/index.js.

### How do I add an MCP server connection with the Smithery CLI?

Search the registry with smithery mcp search [term], then add the server with smithery mcp add <url> --id <id>. Existing connections are listed with smithery mcp list and removed with smithery mcp remove <ids...>.

### How do I call a tool from the Smithery CLI?

Search for it with smithery tool find [query], inspect it with smithery tool get <connection> <tool>, and call it with smithery tool call <connection> <tool> [args], passing the arguments as a JSON string.

### How do I publish an MCP server with the Smithery CLI?

Use smithery mcp publish <url> -n <org/server> for a running server, or smithery mcp publish <bundle.mcpb> -n <org/server> for a packaged bundle, where the .mcpb format is the bundle type the project depends on through the @anthropic-ai/mcpb package.

## Sources

- [arcadeai-labs/smithery-cli on GitHub](https://github.com/arcadeai-labs/smithery-cli)
- [License: AGPL-3.0](https://github.com/arcadeai-labs/smithery-cli/blob/main/LICENSE)
- [Project website](https://smithery.ai)
- [README](https://github.com/arcadeai-labs/smithery-cli/blob/main/README.md)
- [Releases](https://github.com/arcadeai-labs/smithery-cli/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/arcadeai-labs-smithery-cli