# Add the KnowMan MCP server to Crush

Client: Crush

Crush supports local MCP servers over stdio through an `mcp add` entry in your `crushrc`, with `--command` for the executable, `--args` for its arguments and `--env` for environment variables, per the [Crush README](https://raw.githubusercontent.com/charmbracelet/crush/main/README.md). The KnowMan MCP server is a standalone [stdio server](https://www.knowman.io/guides/what-is-an-mcp-server) started with `npx -y @knowman/mcp` on Node 22 or newer, per [the MCP server guide](https://www.knowman.io/guides/mcp-server-knowledge-base). The snippet below applies Crush's documented options to that start command, with your key in `KNOWMAN_API_KEY`.

## crushrc

```bash
# crushrc
# set KNOWMAN_API_KEY in your shell before launching Crush
mcp add knowman --command npx --args -y @knowman/mcp \
  --env KNOWMAN_API_KEY "$KNOWMAN_API_KEY"
```

## Add the server to your crushrc

Crush supports MCP servers through three transport types: `stdio` for command-line servers, `http`, and `sse`, per the [Crush README](https://raw.githubusercontent.com/charmbracelet/crush/main/README.md). The KnowMan MCP server is a standalone stdio server, started with `npx -y @knowman/mcp` on Node 22 or newer, per [the MCP server guide](https://www.knowman.io/guides/mcp-server-knowledge-base), so the local stdio form is the one to use.

Crush reads `crushrc` files, which are Bash with Crush-specific builtins, per the [Crush README](https://raw.githubusercontent.com/charmbracelet/crush/main/README.md). On Unix-like systems it checks `./.crushrc`, then `./crushrc`, then `~/.config/crush/crushrc`, with the same order under Windows paths. `mcp add` registers a local server, `--command` names the executable, `--args` supplies arguments, and `--env` passes environment variables. The snippet below applies these documented options to KnowMan's documented start command.

## Create a KnowMan API key

In the KnowMan web app, open Settings > Connections > Connect an AI agent to create a key. Keys look like `km_...`, and the server uses the key as a Bearer key against KnowMan's HTTP API through the environment variable `KNOWMAN_API_KEY`, per [the MCP server guide](https://www.knowman.io/guides/mcp-server-knowledge-base). Set `KNOWMAN_API_KEY` in your shell before launching Crush, so the `--env` entry in the snippet passes it to the server.

## Sign in once with knowman login

KnowMan documents an alternative to the key in the config: run `npx -p @knowman/mcp knowman login` once, [sign in](https://www.knowman.io/guides/personal-knowledge-base) in the browser, and the saved credential is shared by the CLI and the MCP server, so the env entry can be dropped, per [the MCP server guide](https://www.knowman.io/guides/mcp-server-knowledge-base).

The same package installs the `knowman` CLI, which includes `login`, `status` and `logout` commands, per [the MCP server guide](https://www.knowman.io/guides/mcp-server-knowledge-base). If you prefer to keep the key route, leave the `--env KNOWMAN_API_KEY` entry in place.

## Verify the setup

The Crush README does not document a way to verify that an MCP server connected, per the [Crush README](https://raw.githubusercontent.com/charmbracelet/crush/main/README.md). What you can check is the credential side: the `knowman` CLI includes a `status` command, per [the MCP server guide](https://www.knowman.io/guides/mcp-server-knowledge-base). The KnowMan server exposes `kb_recent`, which lists recently [saved items](https://www.knowman.io/guides/how-to-save-articles), among its tools, per [the MCP server guide](https://www.knowman.io/guides/mcp-server-knowledge-base).

## The KnowMan tools

The KnowMan MCP server exposes these tools, per [the MCP server guide](https://www.knowman.io/guides/mcp-server-knowledge-base). `kb_search` searches saved items by [keyword or meaning](https://www.knowman.io/guides/ai-knowledge-base) and returns titles, URLs and metadata. `kb_ask` answers a question with citations. `kb_get_item` returns the readable content of one item.

`kb_save` saves a URL to the Inbox or the Knowledge Base with an optional note. `kb_recent` lists recent items. `kb_memories` lists saved claims, decisions and playbooks, per [the MCP server guide](https://www.knowman.io/guides/mcp-server-knowledge-base).

## Common problems

Config location. On Unix-like systems Crush checks `./.crushrc`, then `./crushrc`, then `~/.config/crush/crushrc`, and the same order applies under Windows paths, per the [Crush README](https://raw.githubusercontent.com/charmbracelet/crush/main/README.md). Crush respects `XDG_CONFIG_HOME`, so your paths may differ, and `CRUSH_GLOBAL_CONFIG` can override the user config location.

Old JSON config. The legacy JSON format is still supported but deprecated, and any `$(...)` in `crush.json` runs at load time, per the [Crush README](https://raw.githubusercontent.com/charmbracelet/crush/main/README.md). Application state is separate from configuration and should not be edited by hand, per the [Crush README](https://raw.githubusercontent.com/charmbracelet/crush/main/README.md).

Review before you launch. A `crushrc` is trusted code that runs in a full shell, and the README advises not launching Crush in a directory whose config you have not reviewed, per the [Crush README](https://raw.githubusercontent.com/charmbracelet/crush/main/README.md).

## What KnowMan brings to Crush

KnowMan saves articles and links, reads and tags them, answers questions with citations, and keeps memories: claims, decisions and playbooks, per [the personal knowledge base guide](https://www.knowman.io/guides/personal-knowledge-base). Through the server's tools, a client running the server can search that library, ask it questions, and save new URLs into it. For the wider setup story, see [an MCP server for a knowledge base](https://www.knowman.io/guides/mcp-server-knowledge-base) and [a knowledge base for AI agents](https://www.knowman.io/guides/knowledge-base-for-ai-agents).

## Questions

### How do I add an MCP server to Crush?

Add an `mcp add` entry to your `crushrc`, which is Bash with Crush-specific builtins. Use `--command` for the executable, `--args` for its arguments, and `--env` for environment variables. The syntax is documented in the [Crush README](https://raw.githubusercontent.com/charmbracelet/crush/main/README.md).

### Where does Crush read its config from?

On Unix-like systems it checks `./.crushrc`, then `./crushrc`, then `~/.config/crush/crushrc`, with the same order under Windows paths. Crush respects `XDG_CONFIG_HOME`, so your paths may differ. See the [Crush README](https://raw.githubusercontent.com/charmbracelet/crush/main/README.md).

### Does the KnowMan MCP server work with Crush?

Crush documents support for stdio MCP servers alongside `http` and `sse`, per the [Crush README](https://raw.githubusercontent.com/charmbracelet/crush/main/README.md), and the KnowMan server is a standalone stdio server started with `npx -y @knowman/mcp` on Node 22 or newer, per [the MCP server guide](https://www.knowman.io/guides/mcp-server-knowledge-base). The setup on this page combines both projects' documented formats.

### Do I need an API key in the config?

You need one of the two documented routes. Create a key at Settings > Connections > Connect an AI agent and pass it as `KNOWMAN_API_KEY`, or run `npx -p @knowman/mcp knowman login` once, after which KnowMan documents that the env entry can be dropped; both routes are covered in [the MCP server guide](https://www.knowman.io/guides/mcp-server-knowledge-base).

## Related pages

- [Connect your knowledge base through KnowMan's MCP server](https://www.knowman.io/guides/mcp-server-knowledge-base)

- [What Is a Knowledge Base for AI Agents?](https://www.knowman.io/guides/knowledge-base-for-ai-agents)

- [Persistent Memory for AI Agents](https://www.knowman.io/guides/persistent-memory-for-ai-agents)

- [How to Give Your AI Context from What You Read](https://www.knowman.io/guides/give-your-ai-context)

## More in this topic

- [KnowMan MCP server for OpenCode](https://www.knowman.io/integrations/opencode)
- [Connect KnowMan to OpenClaw](https://www.knowman.io/integrations/openclaw)
- [Add the KnowMan MCP server to Devin CLI](https://www.knowman.io/integrations/devin-cli)

## Give Crush your library

Try KnowMan Pro for 14 days with no credit card. [Create your account](https://app.knowman.io/signup)

[Start free](https://app.knowman.io/signup)

Every new account starts with 14 days of Pro. No credit card.

Source: https://www.knowman.io/integrations/crush