mcp-anythingllm

MCP server (stdio) that gives Hermes access to the knowledge base in AnythingLLM: documents uploaded through the AnythingLLM web UI (PDF, Word, web pages, Markdown …), organised in workspaces.

Typical setup: AnythingLLM runs as a container on the harness server (loopback port 3001), LLM and embedding model come from an OpenAI-compatible LLM server. This MCP server only talks to AnythingLLM's developer API.

Requirements

• Python 3.11 or newer — the pinned dependencies require it (rpds-py, PyJWT); the CI runs 3.11 and 3.14.

• A running AnythingLLM instance with the Developer API enabled (Settings → Developer API gives the key). The server talks to it over HTTP, nothing else.

• Optional: read access to AnythingLLM's storage/documents folder — only needed for rag_get.

Related MCP server: mcp-vault-reader

Installation

git clone https://github.com/StefanOOEOrg/mcp-anythingllm.git
cd mcp-anythingllm
python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
cp .env.example .env        # set ANYTHINGLLM_URL and ANYTHINGLLM_API_KEY

Then register it in your MCP client (see Hermes for the profile entry).

Tools

Writing tools are meant for explicit requests or a skill's workflow. A document is named by its source path (or its end, e.g. train-log.md), its title or its storage name.

Configuration (.env)

Project structure

mcp-anythingllm/
├── src/
│   ├── client.py            # AnythingLLM developer API (search, documents, workspaces)
│   ├── config.py            # ANYTHINGLLM_* / LOG_LEVEL from the environment
│   ├── main.py              # entry point (starts the server over stdio)
│   ├── mcp_server.py        # composition root: server + tools
│   ├── server_instance.py   # the shared MCP server instance
│   └── tools/
│       ├── documents.py     # rag_documents / rag_get / rag_add / rag_edit / rag_update / rag_remove
│       └── rag.py           # rag_workspaces / rag_search / rag_answer
├── tests/                   # fake API via httpx.MockTransport, no network
├── scripts/import_wiki.py   # bulk import of a Markdown folder
├── .github/workflows/ci.yml # pytest + pylint on 3.11 and 3.14
├── .env.example             # copy to .env
├── .pylintrc
├── pytest.ini
├── requirements.txt / requirements-dev.txt
├── LICENSE
└── README.md

Development

python3 -m venv venv && venv/bin/pip install -r requirements-dev.txt
venv/bin/python -m pytest          # fake API via httpx.MockTransport, no network
venv/bin/pylint src tests

Hermes

Install the release anywhere (with its own venv and .env) and add it to the profile's config.yaml:

mcp_servers:
  mcp-anythingllm:
    command: /path/to/mcp-anythingllm/.venv/bin/python
    args: [/path/to/mcp-anythingllm/src/main.py]

Importing an existing Markdown folder

venv/bin/python scripts/import_wiki.py ~/notes --default Personal --folder Work=Work --dry-run

Files below a folder Work go to the workspace "Work", everything else to "Personal"; missing workspaces are created. Already imported files are skipped on a rerun.

Scope / Limitations

• A single-user tool, not a service: it runs locally over stdio — no port of its own, no authentication, no multi-user support.

• It needs a running AnythingLLM instance plus its Developer API key; without them every tool fails with a readable message.

• The API key is stored in plain text in .env — keep that file out of the repo and out of logs.

• Several tools write to the knowledge base (rag_add, rag_edit, rag_update, rag_remove); they are meant for explicit requests, not for background use.

• rag_get needs a readable ANYTHINGLLM_DOCUMENTS_DIR; the API itself returns no document text.

• Answers come from your own LLM server through AnythingLLM, so quality and latency depend on that setup — and the API is not part of AnythingLLM's public contract, so it can change between versions.

License

MIT