AnythingLLM MCP Server

A Model Context Protocol (MCP) server that lets MCP-compatible clients (VS Code, Claude Desktop, Cursor, and others) interact with AnythingLLM. Available tools:

Workspace management
Chat and thread operations
Document operations and embeddings
Vector search
System and model inspection

Requirements

Python 3.10+ — verify: python --version or python3 --version.

Download if not installed.

uv (Python package manager) — verify: uv --version.

Install instructions.

AnythingLLM running and reachable — open http://localhost:3001 in a

browser to confirm. If it runs in Docker, make sure the port is published (e.g., -p 3001:3001).

AnythingLLM API key — create one in the AnythingLLM web interface (look

for API Keys or Developer API in Settings). Copy the key and store it securely; it is shown only once.

Installation

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

uv sync reads pyproject.toml and installs all required dependencies into a local virtual environment. You do not need to create or activate the environment manually — uv run handles that automatically.

Configuration

The server reads configuration from these environment variables at startup:

ANYTHINGLLM_BASE_URL: Base URL of your AnythingLLM instance.

Defaults to http://localhost:3001 if not set.

ANYTHINGLLM_API_KEY: API key for authenticating with AnythingLLM.

This value is required.

The server does not load .env files by itself. You must either:

Set the variables in the shell before starting the server.
Use a tool that loads .env files for you.
Pass the variables directly in your MCP client configuration.

Option 1: Set variables in your current shell

PowerShell:

$env:ANYTHINGLLM_BASE_URL = "http://localhost:3001"
$env:ANYTHINGLLM_API_KEY = "your_api_key_here"

Bash:

export ANYTHINGLLM_BASE_URL="http://localhost:3001"
export ANYTHINGLLM_API_KEY="your_api_key_here"

Command Prompt (cmd.exe):

set ANYTHINGLLM_BASE_URL=http://localhost:3001
set ANYTHINGLLM_API_KEY=your_api_key_here

Use the host-exposed URL for your deployment. For Docker port mappings like 3002:3001, set ANYTHINGLLM_BASE_URL to http://localhost:3002 because the MCP server connects from the host, not from inside the container.

Option 2: Use a `.env` file with `uv`

Copy the example file:

PowerShell:

Copy-Item .env.example .env

Bash:

cp .env.example .env

Command Prompt (cmd.exe):

copy .env.example .env

Edit .env so it contains your real values:

ANYTHINGLLM_BASE_URL=http://localhost:3001
ANYTHINGLLM_API_KEY=replace_with_your_real_api_key

Then start the server with:

uv run --env-file .env anythingllm-mcp

This tells uv to load variables from .env before starting the server.

Option 3: Pass variables in your MCP client configuration

Most MCP clients accept an env block in their configuration file (see the Client setup examples below). When the env block contains ANYTHINGLLM_API_KEY and ANYTHINGLLM_BASE_URL, you do not need to export variables in the shell or use a .env file.

Client setup

Replace /path/to/anythingllm-mcp in the examples below with the absolute path where you cloned the repository. Examples:

Linux / macOS: /home/youruser/anythingllm-mcp
Windows: C:\\Users\\youruser\\anythingllm-mcp (use double backslashes \\

inside JSON strings)

VS Code

Add to your user or workspace mcp.json. Open the Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on macOS) and run 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"
      }
    }
  }
}

VS Code supports ${input:name} to prompt for the API key on each session. In a multi-root workspace, prefer an absolute path for --directory if the MCP server lives outside the current folder root.

If VS Code shows only a partial tool list after you update the server or switch from another AnythingLLM integration to this local one:

Run MCP: List Servers and confirm anythingllm or your chosen server name

starts successfully.

Run MCP: Reset Cached Tools to clear stale tool metadata.
Restart the MCP server from MCP: List Servers.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "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"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root, or to the global config at ~/.cursor/mcp.json (Linux/macOS) / %USERPROFILE%\.cursor\mcp.json (Windows):

{
  "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"
      }
    }
  }
}

Note: ANYTHINGLLM_BASE_URL defaults to http://localhost:3001, which is the application port inside the container. If you publish Docker as 3002:3001, use http://localhost:3002 in client configuration.

Run (standalone)

If you already exported the variables in your shell:

uv run anythingllm-mcp

If you want to load them from .env at launch time:

uv run --env-file .env anythingllm-mcp

Development

Install test dependencies and run the test suite:

uv sync --extra dev
uv run pytest

Troubleshooting

"API key is missing" or 401 Unauthorized

The server could not authenticate with AnythingLLM. Check that:

ANYTHINGLLM_API_KEY is set in your environment or in the env block of

your MCP client configuration.

The key matches an active key in AnythingLLM (Settings → API Keys).
The key has no leading or trailing whitespace.

"Connection refused" or timeout

The server could not reach AnythingLLM. Check that:

AnythingLLM is running (open http://localhost:3001 in a browser).
ANYTHINGLLM_BASE_URL points to the correct host and port.
No firewall or VPN is blocking the connection.

Docker port mismatch

If AnythingLLM runs in Docker with a port mapping like 3002:3001:

Inside the container, the application listens on port 3001.
On the host, you access it on port 3002.

Because the MCP server runs on the host (not inside the container), set:

ANYTHINGLLM_BASE_URL=http://localhost:3002

Always use the host port (the left side of the -p or ports: mapping).

MCP server running inside a container (Dev Containers, Docker Compose)

If the MCP server itself runs inside a container (for example, a VS Code Dev Container), localhost refers to that container's own network — not to the host machine. To reach AnythingLLM running on the host or in another container with a published port, use host.docker.internal:

ANYTHINGLLM_BASE_URL=http://host.docker.internal:3001

If both the MCP server and AnythingLLM are containers on the same Docker network (for example, in the same docker-compose.yml), use the service name as hostname instead:

# "anythingllm" is the service name defined in docker-compose.yml
ANYTHINGLLM_BASE_URL=http://anythingllm:3001

In this case, use the container port (3001), not the host-published port.

host.docker.internal is supported on Docker Desktop (Windows and macOS) and on Docker Engine 20.10+ for Linux (requires --add-host=host.docker.internal:host-gateway or the equivalent extra_hosts in Compose).

Security notes

Never commit real API keys.
Use environment variables for secrets.
Use least-privileged AnythingLLM API tokens when possible.

License

MIT

AnythingLLM MCP Server