Skip to main content
Glama

locus-mcp

MCP server for Locus — a local semantic dataspace manager powered by Ollama.

Exposes all Locus HTTP endpoints as MCP tools so any MCP-compatible client (Claude Desktop, Cursor, etc.) can manage dataspaces, ingest documents, and run semantic search.

Requirements

  • Locus running locally or remotely

  • Node.js 18+

Related MCP server: qdrant-mcp

Installation

npm install -g @miguelaperez/locus-mcp --registry=https://npm.pkg.github.com

Or run directly with npx (package is on GitHub, not the npm registry):

npx github:MiguelAPerez/locus-mcp

Note: @miguelaperez/locus-mcp is a GitHub Packages package, not published to the public npm registry. Using npx @miguelaperez/locus-mcp (without github:) will fail unless you've configured your npm registry. Use github:MiguelAPerez/locus-mcp instead.

Configuration

Environment variable

Default

Description

LOCUS_URL

http://localhost:8000

Base URL of the Locus API

MCP client setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "github:MiguelAPerez/locus-mcp"],
      "env": {
        "LOCUS_URL": "http://localhost:8000"
      }
    }
  }
}

Cursor / other clients

{
  "locus": {
    "command": "npx",
    "args": ["-y", "github:MiguelAPerez/locus-mcp"],
    "env": {
      "LOCUS_URL": "http://localhost:8000"
    }
  }
}

mcpo (HTTP proxy)

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "github:MiguelAPerez/locus-mcp"],
      "env": {
        "LOCUS_URL": "http://locus:8000"
      }
    }
  }
}

Tools

Spaces

Tool

Description

list_spaces

List all dataspaces

create_space

Create a new dataspace

delete_space

Delete a dataspace and all its documents

Documents

Tool

Description

list_documents

List all documents in a dataspace

ingest_document

Ingest text into a dataspace

get_document

Retrieve full text of a document by ID

delete_document

Delete a document by ID

Tool

Description

search

Semantic search over a dataspace (query, k, full)

Settings & health

Tool

Description

health_check

Check if Locus is reachable

get_settings

Get current Ollama URL and embedding model

update_settings

Update Ollama URL and/or embedding model

Development

npm install
npm run dev      # watch mode
npm test         # run tests
npm run build    # compile to dist/

License

MIT

Available Tools

11 tools
create_spaceA

Create a new dataspace in Locus

Inputs: name (required).

delete_documentA

Delete a document by its ID from a Locus dataspace

Inputs: space (required), doc_id (required).

delete_spaceA

Delete a dataspace and all its documents from Locus

Inputs: space (required).

get_documentA

Retrieve the full text of a document by its ID from a Locus dataspace

Inputs: space (required), doc_id (required).

get_settingsA

Get the current Locus settings (Ollama URL and embedding model)

Inputs: no named parameters.

health_checkA

Check if the Locus service is healthy and reachable

Inputs: no named parameters.

ingest_documentA

Ingest a document into a Locus dataspace. Provide either file_path (preferred, reads file locally without loading content into context) or text.

Inputs: space (required), text, filename, file_path.

list_documentsB

List all documents in a Locus dataspace

Inputs: space (required).

list_spacesA

List all dataspaces in Locus

Inputs: no named parameters.

update_settingsA

Update Locus settings (Ollama URL and/or embedding model). Only works if settings are not locked via environment variables.

Inputs: ollama_url, embed_model.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: spaces, documents, search, settings, and health. Even closely related tools like list_documents and search are clearly differentiated by listing all versus semantic retrieval.

    Naming Consistency5/5

    Tool names consistently follow a clear verb_noun pattern such as list_spaces, create_space, delete_document, and update_settings. The use of ingest_document instead of create_document is still intuitive and does not break the overall pattern.

    Tool Count5/5

    With 11 tools, the server is well-scoped for managing dataspaces, documents, search, settings, and health. Each tool serves a clear purpose without redundancy or bloat.

    Completeness4/5

    The tool surface covers core lifecycle operations for spaces and documents, plus search, settings, and health checks. Minor gaps exist, such as no update/rename for spaces and no replace/update operation for documents, but these are unlikely to block the primary workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for document ingestion and semantic search on Qdrant. Enables ingesting local documents, generating embeddings with OpenAI, and performing vector search with metadata filters.
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Local-first RAG indexing and semantic search MCP server. Enables document retrieval and context-aware queries using local embedding models.
      3
      6 npm
      MIT