locus-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@locus-mcp search 'quantum computing' in my research space"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.comOr run directly with npx (package is on GitHub, not the npm registry):
npx github:MiguelAPerez/locus-mcpNote:
@miguelaperez/locus-mcpis a GitHub Packages package, not published to the public npm registry. Usingnpx @miguelaperez/locus-mcp(withoutgithub:) will fail unless you've configured your npm registry. Usegithub:MiguelAPerez/locus-mcpinstead.
Configuration
Environment variable | Default | Description |
|
| 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 all dataspaces |
| Create a new dataspace |
| Delete a dataspace and all its documents |
Documents
Tool | Description |
| List all documents in a dataspace |
| Ingest text into a dataspace |
| Retrieve full text of a document by ID |
| Delete a document by ID |
Search
Tool | Description |
| Semantic search over a dataspace ( |
Settings & health
Tool | Description |
| Check if Locus is reachable |
| Get current Ollama URL and embedding model |
| 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 toolscreate_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.
searchA
Semantic search over documents in a Locus dataspace using natural language
Inputs: query (required), space (required), k, full.
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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
An MCP server for search and retrieval over a local LanceDB database
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA server that enables seamless integration between local Ollama LLM instances and MCP-compatible applications, providing advanced task decomposition, evaluation, and workflow management capabilities.6-
- AlicenseNot gradedqualityDmaintenanceMCP 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
- AlicenseAqualityDmaintenanceLocal-first RAG indexing and semantic search MCP server. Enables document retrieval and context-aware queries using local embedding models.36 npmMIT
- FlicenseAqualityCmaintenanceMCP server that enables semantic search over local PDF collections using local RAG, with automatic indexing of new documents.5-