TL;DR

I built an open-source MCP server that lets AI agents (GitHub Copilot, Claude Desktop, Cursor) control AnythingLLM programmatically — managing workspaces, chatting with documents, uploading content, running vector searches, and inspecting system settings. All through 23 typed tools, using a single Python file and stdio transport.

Repository: github.com/andreperez/anythingllm-mcp

The Problem: AI Assistants Can’t Reach Your Knowledge Base

If you use AnythingLLM to organize documents into workspaces, chat with them, and run vector searches, you probably interact with it through its web UI. That’s fine for manual work — but what happens when you want an AI assistant to do it for you?

Imagine telling your coding agent:

“Search my research papers workspace for everything related to neurology, then summarize the top results.”

Or:

“Create a new workspace called ‘Q1 Reports’, upload this financial document, embed it, and give me a summary.”

Without a bridge between the AI agent and AnythingLLM, you’d have to do each step manually: open the UI, click through menus, copy and paste results back. That’s the gap I wanted to close.

The Solution: Model Context Protocol (MCP)

The Model Context Protocol (MCP), created by Anthropic, is an open standard that allows AI models to interact with external tools and data sources through a structured interface. Think of it as a USB-C port for AI — a standardized way for any compatible client to discover and call tools from any compatible server.

An MCP server exposes tools (functions the AI can call), resources (data the AI can read), and prompts (reusable message templates). The client — VS Code, Claude Desktop, Cursor, or any MCP-compatible host — discovers them automatically and uses them in context.

I built an MCP server that wraps the entire AnythingLLM REST API into 23 typed tools that any MCP client can call.

What the Server Does

The server covers the full lifecycle of knowledge management in AnythingLLM:

Workspace Management

• List, create, update, delete workspaces
• Configure chat mode (conversational vs. query-only), temperature, similarity threshold, and LLM provider per workspace

Chat & Threads

• Send messages to any workspace (chat or query mode)
• Retrieve conversation history with full metadata
• Create and manage threads for parallel conversation tracks within a workspace

Document Operations

• List all documents in the system
• Upload content from URLs (web pages, PDFs) — AnythingLLM fetches and processes them
• Upload raw text directly as a document
• Update embeddings — move documents in or out of a workspace’s vector store

Vector Search

• Semantic search across embedded documents with configurable top_n and similarity thresholds

System & Administration

• Inspect system settings — LLM provider, embedding engine, vector DB, model preferences
• Get vector counts across the system
• Export all chat logs for backup or analysis
• List embed configurations (public chat widgets)
• List available models via the OpenAI-compatible endpoint

Architecture: Single File, Zero Complexity

The entire server is a single Python file (anythingllm_mcp.py, ~660 lines) built on top of:

• FastMCP — the high-level Python SDK for MCP servers
• httpx — async HTTP client for calling AnythingLLM’s REST API
• Pydantic — for type validation and schema generation

┌──────────────────────┐       stdio        ┌──────────────────────┐
│  MCP Client          │◄──────────────────►│  anythingllm_mcp.py  │
│  (VS Code / Claude / │   JSON-RPC         │  (FastMCP Server)    │
│   Cursor)            │                    │                      │
└──────────────────────┘                    └──────────┬───────────┘
                                                       │ httpx
                                                       ▼
                                            ┌──────────────────────┐
                                            │  AnythingLLM         │
                                            │  REST API (:3001)    │
                                            └──────────────────────┘

Each tool is a decorated async function with full type hints. FastMCP reads the type annotations and docstrings to automatically generate the JSON schemas that clients use for tool discovery. This means the code is the documentation — no separate schema files to maintain.

Example: Vector Search Tool

@mcp.tool(
    name="anythingllm_search",
    annotations={
        "readOnlyHint": True,
        "destructiveHint": False,
        "idempotentHint": True,
    },
)
async def search_workspace(
    slug: str,
    query: str,
    top_n: int = 4,
    score_threshold: Optional[float] = None,
) -> str:
    """Search for relevant document chunks within a workspace 
    using vector similarity."""
    body: dict = {"query": query, "topN": top_n}
    if score_threshold is not None:
        body["scoreThreshold"] = score_threshold
    result = await _api(
        f"/workspace/{slug}/vector-search",
        method="POST",
        body=body,
    )
    return json.dumps(result, indent=2)

The annotations dict tells the client that this tool is read-only and safe to call repeatedly — which helps the AI decide when and how to use it.

How to Set It Up (5 Minutes)

Prerequisites

• Python 3.10+
• uv (modern Python package manager)
• AnythingLLM running (locally or remote)
• An AnythingLLM API key (Settings → Developer)

Install

git clone https://github.com/andreperez/anythingllm-mcp.git
cd anythingllm-mcp
uv sync

Configure Your Client

VS Code — Add to your mcp.json (Command Palette → "MCP: Open User Configuration"):

{
  "servers": {
    "anythingllm": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/anythingllm-mcp",
        "anythingllm-mcp"
      ],
      "env": {
        "ANYTHINGLLM_API_KEY": "${input:anythingllm_api_key}",
        "ANYTHINGLLM_BASE_URL": "http://localhost:3001"
      }
    }
  }
}

Claude Desktop — Edit claude_desktop_config.json:

{
  "mcpServers": {
    "anythingllm": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/anythingllm-mcp",
        "anythingllm-mcp"
      ],
      "env": {
        "ANYTHINGLLM_API_KEY": "YOUR_API_KEY",
        "ANYTHINGLLM_BASE_URL": "http://localhost:3001"
      }
    }
  }
}

Replace /path/to/anythingllm-mcp with the absolute path where you cloned the repository.

Real-World Use Case

Here’s a concrete example. I had a workspace with academic papers about technical analysis and wanted to find specific content:

Me (in VS Code, using GitHub Copilot): “Search my ‘papers’ workspace for RSI divergence strategies.”

Copilot automatically called anythingllm_search with slug="papers" and query="RSI divergence strategies", got back the top vector-matched document chunks with similarity scores, and then summarized the findings — all without me ever leaving my editor.

The same workflow works for any knowledge base: internal documentation, legal contracts, research papers, product specs. If it’s in AnythingLLM, the AI can now reach it.

Design Decisions Worth Mentioning

Why stdio transport? It’s the simplest and most universal. Every MCP client supports it. The server starts as a subprocess of the client, communicates over stdin/stdout, and dies when the client disconnects. No ports to manage, no authentication layer to build on top.

Why a single file? An MCP server should be easy to audit. With 660 lines in one file, anyone can read the entire codebase in minutes and understand exactly what the AI agent can and cannot do. No hidden abstractions.

Why tool annotations? The readOnlyHint, destructiveHint, and idempotentHint annotations inform the client about the tool's behavior. A client can use this to auto-approve read-only tools while requiring confirmation for destructive ones (like delete_workspace). This is a small detail that significantly improves the user experience.

Why async? AnythingLLM API calls can take time, especially when processing documents or running LLM inference. Async functions with httpx ensure the server doesn't block while waiting for responses.

What’s Next

The server currently wraps the most common AnythingLLM API endpoints. Future additions could include:

• File upload support (binary documents, not just URLs and raw text)
• Workspace-level permission management for multi-user instances
• Streaming chat responses
• PyPI distribution for simpler installation (uvx anythingllm-mcp)

Try It

The project is MIT-licensed and available on GitHub:

github.com/andreperez/anythingllm-mcp

If you use AnythingLLM as your knowledge base and want your AI assistants to interact with it natively, give it a try. Issues and contributions are welcome.

Specialist in software development and product support. If you found the article useful, follow me on my social networks. If you didn’t like it, or found something wrong, that’s okay… constructive criticism is welcome.

Introdução

O tempo é a moeda de troca mais valiosa… talvez não seria se tivéssemos uma vida infinita, mas esse não é o caso. Por isso, quanto mais tempo você gasta com determinado trabalho, com mais afinco você deveria protegê-lo. Imagine a dor de cabeça de ter que recomeçar um trabalho que levou anos para ser concluído. É por isso que existem diversas ferramentas de backup.

Estas ferramentas possuem recursos e estratégias diferentes, no que tange “o que”, “como” e “quando”. A escolha de tais recursos depende da necessidade do usuário.

• “O que?” — Do que o backup será feito? Disco, partição, ou arquivos?
• “Como?” — Backup completo, diferencial ou incremental? Qual o nível de compressão?
• “Quando?” — Qual a periodicidade?

O que é o restic

O restic é um programa de backup de código aberto escrito na linguagem de programação Go, que funciona em diversos sistemas operacionais. É capaz de realizar backups de arquivos, mas não de discos e partições.

Ele funciona com o conceito de repositório e snapshots, e por isso lembra muito o git.

Se fossemos comparar “a grosso modo”, a diferença básica é que o restic é exclusivamente voltado para o controle de backups, enquanto o git é exclusivamente voltado para o controle de versão. Além disso, o repositório do restic é encriptado e necessita de uma senha, coisa que não existe no git.

Ainda não existe uma ferramenta gráfica, mas para quem está acostumado com a linha de comando, isso não é um problema. Nada de outro mundo.

Na minha experiência pessoal, notei que ele é rápido e eficiente na economia de espaço, visto que a cada backup que é realizado, apenas a diferença é salva.

Pressupostos

Nível de dificuldade: médio para avançado

Conhecimentos: linha de comando do seu sistema operacional favorito (Windows, Linux, MacOS, BSDs).

1. Instalação

A instalação é igual uma receita de bolo: basta entrar no site oficial, ler a documentação e seguir os passos. Aqui eu coloquei um resumo de todos os comandos, de acordo com o sistema operacional:

# Alpine Linux
 apk add restic

# Arch Linux
 pacman -S restic

# Debian, Ubuntu e derivados
 apt-get install restic

# Fedora
 dnf install restic

# MacOS via Homebrew
 brew install restic

# MacOS via MacPorts
 sudo port install restic

# Nix & NixOS
 nix-env — install restic

# OpenBSD
 pkg_add restic

# FreeBSD
 pkg install restic

# OpenSuse
 zypper install restic

# RHEL & CentOS Stream 8 & 9
 dnf install epel-release
 dnf install restic

# RHEL7/CentOS
 yum install yum-plugin-copr
 yum copr enable copart/restic
 yum install restic

# Solus
 eopkg install restic

# Windows via Scoop
 scoop install restic

2. Criando um backup

Para criar um backup novo, primeiro precisamos criar o repositório de backups, usando a seguinte sintaxe:

$ restic init --repo <pasta_do_repositório>

Exemplo:

$ restic init --repo /mnt/disco_1/restic-repo
enter password for new repository:
enter password again:
created restic repository 085b3c76b9 at /mnt/disco_1/restic-repo
Please note that knowledge of your password is required to access the repository.
Losing your password means that your data is irrecoverably lost.

O próximo passo é fazer o backup.

Digamos que você queira fazer um backup de uma lista de pastas e arquivos. Então o mais recomendável é colocar essa lista num TXT. Isso facilita a manutenção.

O mesmo pode ser feito para os arquivos e pastas a serem ignorados, colocando-os em outro TXT.

A senha também pode ser armazenada num outro arquivo TXT (num local seguro e que ninguém consiga acessar)… para evitar o trabalho chato de toda hora ter que digitá-la.

Após termos os TXTs em mãos, poderíamos fazer o backup mais ou menos com esse comando:

$ restic -r <pasta_do_repositório> backup --files-from <arquivo_TXT_1> --exclude-file=<arquivo_TXT_2> --password-file <arquivo_TXT_3>

Exemplo:

$ restic -r /media/usuario/Disco_Externo/Backups/restic backup --files-from /home/usuario/restic/include.txt --exclude-file =/home/usuario/restic/exclude.txt --password-file /etc/restic/.restic_pwd

Feito. Simples assim.

Toda vez que for realizado um backup, um novo snapshot é criado no repositório. Para listá-los usamos este comando:

$ restic -r <pasta_do_repositório> snapshots

3. E agora, se eu precisar restaurar?

No Linux, podemos montar um determinado snapshot via FUSE:

$ mkdir /mnt/restic
$ restic -r /srv/restic-repo mount /mnt/restic
enter password for repository:
Now serving /srv/restic-repo at /mnt/restic
Use another terminal or tool to browse the contents of this folder.
When finished, quit with Ctrl-c here or umount the mountpoint.

No Windows ainda não temos esse recurso… mas podemos usar um comando que lista os arquivos de um snapshot:

$ restic -r E:\Backup-restic\Sources ls latest

O comando ls pode resultar numa lista muito extensa. Se quisermos procurar um arquivo, é mais fácil redirecionar a saída para um arquivo TXT, e depois neste arquivo realizar a busca:

$ restic -r E:\Backup-restic\Sources ls latest > arquivos.txt

E para simplesmente restaurar tudo, bastaria executar esse comando:

$ restic -r /srv/restic-repo restore latest --target /tmp/restore-art

… salientando que “latest” se refere ao último snapshot. Para restaurar um snapshot anterior, basta referenciar o ID do mesmo.

4. Automatizando tudo

Para não ter que entrar na linha de comando toda hora e manualmente ter que fazer o backup, é melhor agendar a tarefa numa execução automática.

Assim o risco do esquecimento é eliminado, além de economizar o tempo que seria gasto fazendo essa tarefa.

No Windows temos o Agendador de Tarefas. Aqui eu mostro um script Powershell que executa todo dia às 18:00:

No script Powershell apenas há o comando para fazer o backup, nada além disso. Lembre-se, na correria do seu dia-a-dia, você não quer ser importunado com essa coisa chata.

No Linux criei o agendamento via Anacron. Configurei para executar uma vez por dia, toda vez que a máquina iniciar, após 5 minutos. Nesse caso é um script Bash:

5. Considerações Finais

Ao longo da minha experiência com TI, já testei diversas ferramentas de backup. Para o backup de arquivos rotineiros, o restic supre a exigência.

Ele oferece possibilidades mais avançadas, como por exemplo usar um servidor REST, fazer backup na nuvem, etc.

Todavia é recomendável usar outra ferramenta para fazer o backup de disco e de partições, possuindo um plano de recuperação de desastre mais robusto. Alguns exemplos são Clonezilla, partimage, partclone, EaseUS. No Windows recomendo o EaseUS pela sua facilidade.

Sumário

1. Definições básicas do Protractor (pode pular se já sabe!)
2. Imprimindo stack traces
3. Gerando um relatório de pizza para impressionar a diretoria🍕
4. Debugando o teste E2E no VS Code
5. Debugando o teste E2E no Chrome

1. Definições básicas do Protractor

• O que é o Protractor?

Conforme o site oficial, é um framework de teste ponta-a-ponta para aplicações Angular e AngularJS. A sua utilidade é rodar testes automatizados nas aplicações web, interagindo como se fosse o usuário, e assim descobrindo comportamentos inesperados.

• Como o Protractor funciona?

Basicamente, ele funciona como uma aplicação Node.js, que engloba um framework de testes (exemplo: Jasmine e Mocha) e um framework de automação de browser (Selenium).

O funcionamento dos testes é definido por dois itens principais: os arquivos de testes (arquivos spec) e o arquivo de configuração.

• Um exemplo rápido

A execução dos testes é impressa no console. Por padrão, a biblioteca para imprimir estes resultados é o jasmine-spec-reporter.

2. Imprimindo stack traces

• displayStacktrace — para que serve?

No arquivo de configuração do Protractor, é possível definir a opção displayStacktrace.

A opção displayStacktrace, da biblioteca jasmine-spec-reporter, permite o ajuste do detalhamento dos erros encontrados.

Quando está configurada com a opção ‘pretty’, ela apresenta a pilha de chamadas causadora do erro (stack trace), organizadas por contexto. O mais importante desse recurso são duas informações: código-fonte e linha\coluna onde ocorreu o erro.

Um exemplo:

O que acontece quando esta opção está desligada? O mesmo erro é apresentado dessa forma:

Note que o código-fonte e a respectiva linha\coluna geradores do erro não foram apresentados, apenas a descrição do teste.

• É importante ressaltar a Pull Request 467 de 22 de março-2020. As opções válidas são none, raw e pretty. Antes disso, eram true ou false.
• Desde então, se a opção está como true ou false (ou qualquer outro valor inválido), o valor default é none.

3. Gerando um relatório de pizza para impressionar a diretoria🍕

Podemos automatizar ainda mais o teste automatizado…😂

Existe uma biblioteca, denominada protractor-html-reporter-2, que emite um relatório analítico dos testes, com gráficos de pizza e a totalização de acertos e defeitos.

Além disso, ele consegue tirar screenshots das telas, no momento exato em que algum teste falhou.

O relatório é muito didático, podendo ser entendido por qualquer pessoa que não seja da área de desenvolvimento.

Criando um relatório

Primeiro é necessário instalar as bibliotecas na aplicação:

npm i protractor-html-reporter-2 --save-dev
npm i fs-extra --save-dev

Ok. Agora vamos configurar a ferramenta.

Para não impactar o que já funciona (supondo que sua aplicação possua um pipeline com continuous integration), recomendo que seja criado um arquivo de configuração à parte para o Protractor, exclusivamente para emitir este relatório.

Se o arquivo padrão de configuração é protractor.conf.js, outro arquivo com nome protractor-report.conf.js poderia ser criado:

Para facilitar a vida, no package.json poderia ser adicionado um novo atalho de script:

“e2e:report”: “protractor ./e2e/protractor-report.conf.js”,

Teoricamente está tudo pronto. Agora é só rodar o comando:

npm run e2e:report

Resultado:

4. Debugando o teste E2E no VS Code

Acredito que esta informação é pouco disseminada, mas é possível realizar o debug do teste E2E no VS Code.

Basta configurar o VS Code conforme abaixo:

Recomendo a criação de um arquivo de configuração a parte (exemplo: protractor-debug.conf.js), apenas com um timeout maior, para o sistema não fechar durante a depuração.

No trecho a ser debugado, troque it por fit, e coloque um breakpoint logo abaixo:

5. Debugando o teste E2E no Chrome

“Ah, mas eu não uso o VS Code, prefiro o vi!”

Ok, também é possível debugar no Chrome, independente de qualquer editor ou IDE.

• No seu editor, no trecho a ser debugado, troque it por fit, e logo abaixo coloque a keyword debugger:

• Rode este comando no terminal:

node --inspect-brk ./node_modules/protractor/bin/protractor ./e2e/protractor-debug.conf.js

• Abra o Chrome no endereço chrome://inspect/#devices

• Clique no link inspect
• Uma janela do Chrome abrirá:

• Tecle F8
• Após isso, o debugger do Chrome cairá na linha onde foi escrito debugger:

Pronto. Outra maneira de fazer a mesma coisa.

Referências:

1. https://github.com/bcaudan/jasmine-spec-reporter/pull/467
2. https://www.protractortest.org/#/debugging#disabled-control-flow
3. https://www.protractortest.org/#/api-overview
4. https://www.npmjs.com/package/protractor-html-reporter-2
5. https://github.com/angular/angular-cli/issues/10289
6. https://www.hhutzler.de/blog/angular-testing-protractor/
7. https://www.npmjs.com/package/fs-extra
8. https://medium.com/@praveendavidmathew/creating-html-reports-for-protractor-7d9830ebf428
9. https://applandeo.com/blog/automated-testing-of-angular-application-using-protractor/