# anythingllm-mcp

A small, safe helper that lets an AI assistant (like Claude) **search and ask
questions about your own documents** — the ones you've stored in
[AnythingLLM](https://anythingllm.com).

New to this? No problem. This README explains everything step by step and defines
the jargon as it comes up. If you can install an app and copy-paste a few lines,
you can use this.

---

## The 30-second version

- **[AnythingLLM](https://anythingllm.com)** is an app that stores your documents
  and lets you chat with them ("What does my handbook say about vacation days?").
- **[MCP](https://modelcontextprotocol.io)** (Model Context Protocol) is a standard
  way for AI assistants to use outside tools. Think of it as a **power strip**: an
  assistant plugs into it and suddenly has new abilities.
- **This project is one of those plugs.** Once connected, your AI assistant can
  ask *your* AnythingLLM documents questions and get answers — without you copying
  and pasting anything.

It is **read-only**: it can *look things up*, but it can never change, delete, or
mess up your AnythingLLM data. More on that below.

---

## What it can do

Once connected, your assistant gains four abilities ("tools"):

| Tool | In plain English |
|------|------------------|
| `check_auth` | "Am I connected to AnythingLLM correctly?" |
| `list_workspaces` | "What collections of documents do I have?" (AnythingLLM calls these **workspaces**) |
| `list_documents` | "What files are inside this workspace?" |
| `query_workspace` | "Answer this question using the documents in this workspace." This is the main one. |

That's the whole toolbox. Nothing that can write, delete, or reconfigure anything.

---

## Before you start, you need three things

1. **Node.js, version 18 or newer.** Node is the program that runs this helper.
   Check if you already have it by opening a terminal and typing:
   ```
   node --version
   ```
   If you see something like `v20.11.0`, you're set. If you get an error,
   [install Node here](https://nodejs.org) (the "LTS" version is the safe choice).

2. **AnythingLLM up and running**, and reachable in your browser (for many people
   that's `http://localhost:3001`).

3. **An AnythingLLM API key.** An *API key* is like a password that lets programs
   talk to AnythingLLM on your behalf. To get one: open AnythingLLM →
   **Settings** → **Tools** → **Developer API** → create a key, and copy it
   somewhere safe. You'll paste it into your setup in a moment.

   > 🔒 Treat this key like a password. Don't post it publicly or commit it to
   > GitHub. (This tool is built so the key never has to appear in your chat.)

---

## Install it

In a terminal, download the project and install the pieces it needs:

```bash
git clone https://github.com/DezGDNY/anythingllm-mcp.git
cd anythingllm-mcp
npm install
```

- `git clone` copies the project onto your computer.
- `npm install` downloads the small libraries this project depends on. (`npm`
  comes with Node.) You'll see it create a `node_modules` folder — that's normal.

That's it — there's nothing to "build." The helper is ready to run.

---

## Connect it to your AI assistant

An MCP helper doesn't run on its own; your assistant starts it when needed. You
tell the assistant about it by adding a few lines to its configuration file. For
example, in **Claude Code** (`.mcp.json`) or **Claude Desktop**
(`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "anythingllm": {
      "command": "node",
      "args": ["/full/path/to/anythingllm-mcp/index.js"],
      "env": {
        "ANYTHINGLLM_BASE_URL": "http://localhost:3001",
        "ANYTHINGLLM_API_KEY": "paste-your-key-here"
      }
    }
  }
}
```

What each part means:

- **`command` / `args`** — how to start the helper: run `node` on this project's
  `index.js`. Use the *full* path to the file (e.g. on Windows,
  `C:\\Users\\you\\anythingllm-mcp\\index.js` — note the double backslashes in JSON).
- **`env`** — settings passed to the helper when it starts:
  - `ANYTHINGLLM_BASE_URL` — the web address where your AnythingLLM lives. Leave
    it as `http://localhost:3001` unless yours is elsewhere. (You don't need to
    add `/api/v1`; the helper adds that for you.)
  - `ANYTHINGLLM_API_KEY` — the key you copied earlier.

Save the file and **restart your assistant** so it picks up the new helper.

> **Tip:** putting the key in the `env` block here means it's handled by your
> assistant, not typed into a chat. If you'd rather not keep the key in this file
> at all, you can set it as an environment variable on your system instead — the
> helper reads `ANYTHINGLLM_API_KEY` from wherever it's provided.

---

## Try it

Ask your assistant something like:

> "Use the anythingllm tools to ask my *Project Docs* workspace what our refund
> policy is, and show me which documents the answer came from."

Behind the scenes it calls `query_workspace`, and you get an answer grounded in
your actual documents, with the sources listed.

By default, questions run in **`query` mode**, which means the answer comes
*only* from your documents (it won't make things up from general knowledge). If
you'd rather let the assistant blend in its own knowledge, ask it to use
**`chat` mode** instead.

---

## If something doesn't work

**"Not authenticated" / auth errors** — the API key is missing or wrong. Double-
check you copied the whole key, and that `ANYTHINGLLM_BASE_URL` points at your
actual AnythingLLM address.

**"Failed to connect" in your assistant** — the helper couldn't start. The two
usual causes:

- **The assistant can't find `node`.** Some assistants start helpers with a
  *stripped-down environment* — a bare setup where the system doesn't know where
  `node` is installed. If you hit this, point `command` at the full path to your
  `node` program instead of just `"node"` (find it by running `where node` on
  Windows or `which node` on macOS/Linux).
- **The key wasn't passed in.** Make sure the `env` block above is filled in.

**Want to see what actually happened?** Start the helper by hand to read its
messages:
```bash
node /full/path/to/anythingllm-mcp/index.js
```
If it prints `anythingllm-mcp ready …` and then seems to "hang," that's actually
**success** — it's running and waiting for your assistant to talk to it. Press
`Ctrl+C` to stop. If it prints an error instead, that error tells you what's
wrong.

---

## Is it safe? (Yes — here's why)

This helper can only **read** and **ask questions**. On purpose, it has **no**
tools that create, delete, or change anything in AnythingLLM — no deleting
workspaces, no editing documents, no changing settings. So even if an AI
assistant went completely haywire, the worst it could do through this helper is
*look things up*. Your data is safe.

It also keeps **no secrets in the code**. Your address and key come from the
settings you provide, never from this file — which is why it's safe to share and
publish.

---

## How it works (optional, for the curious)

It's one small file (`index.js`). When your assistant starts it, the helper:

1. reads your AnythingLLM address and key from the environment,
2. waits for the assistant to ask for one of the four tools,
3. makes a normal web request to AnythingLLM's API, and
4. hands the answer back.

It uses the official
[MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) and Node's
built-in networking — no heavy dependencies.

---

## License

[MIT](LICENSE) — free to use, change, and share. Please keep the copyright line.