arcana-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., "@arcana-mcp search for deployment notes"
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.
arcana-mcp
Semantic vector DB as an MCP server for Claude Code — SQLite + FTS5 + local ONNX embeddings.
Gives Claude persistent, searchable project knowledge across conversations. Index files, store findings, search semantically — all through MCP tools.
Prerequisites
Python 3.12+
uv (recommended) — fast Python package manager that provides
uvxfor running tools without global installs:# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # Or via Homebrew brew install uv
On first use, arcana-mcp downloads the embedding model (~130MB) to ~/.arcana/models. This is automatic but requires internet.
Related MCP server: ClaudeX
Install
Claude Code Plugin (recommended)
claude plugin marketplace add samelie/arcana-mcp
claude plugin install arcana-mcpThis installs the MCP server, skills (/arcana:arcana-search, /arcana:arcana-absorb), command (/arcana:search), agent (arcana-researcher), and orientation protocol automatically.
Manual (with uvx)
pip install arcana-mcpAdd to your .mcp.json:
{
"mcpServers": {
"arcana": {
"command": "uvx",
"args": ["arcana-mcp", "serve"]
}
}
}uvx runs arcana-mcp in an isolated environment — no need to manage virtualenvs yourself.
Manual (without uvx)
If you prefer not to use uv, run the server directly:
pip install arcana-mcp{
"mcpServers": {
"arcana": {
"command": "arcana-mcp",
"args": ["serve"]
}
}
}Make sure arcana-mcp is on your PATH (e.g. installed in an active virtualenv or with pipx).
Tools
Tool | Description |
| Index a file or directory into the DB |
| Store a memory entry with embedding |
| Hybrid semantic + FTS5 search (best default) |
| Pure semantic (cosine similarity) search |
| Keyword/regex search via FTS5 |
| Read full content of a resource |
| List direct children at a URI |
| Show recursive tree at a URI |
| Get metadata + chunk count for a resource |
| Remove a resource (with optional recursive) |
| Create a directory at a URI |
| Move/rename a resource |
Skills
/arcana:arcana-absorb <path>
Generates knowledge files optimized for Claude retrieval. Surveys a directory, synthesizes structured knowledge, and indexes it into Arcana. Re-runnable — updates stale files, removes orphans.
/arcana:arcana-search
Quick access to search, store, and browse project knowledge. Use arcana_search for hybrid search, arcana_add_memory for quick findings, arcana_add_resource for indexing files.
Commands
/arcana:search <query>
Quick-invoke search — runs arcana_search with the given query and returns results directly.
Agents
arcana-researcher
Lightweight agent for delegating knowledge searches to a subagent. Searches Arcana, reads top results, returns a focused summary. Keeps main conversation context clean.
Configuration
Environment Variable | Default | Description |
|
| SQLite database path |
|
| ONNX model cache directory |
Architecture
SQLite + FTS5: Full-text search with trigram tokenization
fastembed: Local ONNX embeddings (
BAAI/bge-small-en-v1.5, 384 dimensions)Hybrid search: 0.7 × semantic + 0.3 × FTS5 for best-of-both ranking
Markdown chunking: Splits on
#headings into ~2000 char segmentsMCP transport: stdio via FastMCP
Releasing
From the monorepo root, commit and push your changes, then run:
# Release the current version in pyproject.toml
./packages/arcana-mcp/scripts/release.sh
# Or bump + release in one step
./packages/arcana-mcp/scripts/release.sh 0.2.0The script will:
Validate you're on
mainwith a clean treeOptionally bump
pyproject.tomland commitWait for the monorepo sync workflow to push to
samelie/arcana-mcpVerify the remote version matches
Create a GitHub release (
v0.x.x) which triggers the PyPI publish workflow
License
MIT
Available Tools
12 toolsarcana_add_memoryB
Store a memory entry as a resource with embedding.
Args:
role: Memory role (e.g. 'user', 'assistant', 'system').
content: The memory content to store.
Inputs: role (required), content (required). Returns: result
arcana_add_resourceB
Add a file or directory as a resource into the context database.
Args:
path: Local file or directory path to index.
to: Target arcana:// URI (optional, auto-determined if empty).
reason: Why this resource is being added.
Inputs: path (required), to, reason. Returns: result
arcana_findA
Semantic search — embed query, cosine similarity against all chunks.
Args:
query: Natural language search query.
target_uri: Scope search to a specific arcana:// URI prefix (optional).
limit: Max number of results (default 10).
Inputs: query (required), target_uri, limit. Returns: result
arcana_grepB
Keyword/regex search — FTS5 for simple terms, Python re fallback.
Args:
uri: arcana:// URI to search within.
pattern: Search pattern (keyword or regex).
case_insensitive: Case-insensitive matching.
Inputs: uri, pattern, case_insensitive. Returns: result
arcana_lsB
List direct children at a arcana:// URI.
Args:
uri: arcana:// URI to list (default: root).
Inputs: uri. Returns: result
arcana_mkdirA
Create a directory at a arcana:// URI.
Args:
uri: arcana:// URI for the new directory.
Inputs: uri (required). Returns: result
arcana_mvC
Move/rename a resource.
Args:
from_uri: Source arcana:// URI.
to_uri: Destination arcana:// URI.
Inputs: from_uri (required), to_uri (required). Returns: result
arcana_readB
Read full content of a resource (concatenated chunks in order).
Args:
uri: arcana:// URI to read.
Inputs: uri (required). Returns: result
arcana_rmA
Remove a resource (CASCADE deletes chunks, FTS triggers clean up).
Args:
uri: arcana:// URI to remove.
recursive: Remove all resources under this URI prefix.
Inputs: uri (required), recursive. Returns: result
arcana_searchA
Hybrid search — 0.7 * semantic + 0.3 * FTS5, merged and ranked.
Args:
query: Natural language search query.
target_uri: Scope search to a specific arcana:// URI prefix (optional).
limit: Max number of results (default 10).
Inputs: query (required), target_uri, limit. Returns: result
arcana_statC
Get metadata for a resource.
Args:
uri: arcana:// URI to get metadata for.
Inputs: uri (required). Returns: result
arcana_treeB
Show recursive tree at a arcana:// URI.
Args:
uri: arcana:// URI to show tree for (default: root).
Inputs: uri. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool has a distinct purpose: memory vs resource addition, different search modes (semantic, keyword, hybrid), and clear navigation vs content operations. No ambiguity.
All tools follow the consistent pattern 'arcana_verb' or 'arcana_verb_noun' with snake_case (e.g., arcana_add_memory, arcana_ls, arcana_search). Conventions are uniform.
12 tools is well-scoped for a hierarchical resource and memory system, covering CRUD, navigation, search, and metadata retrieval without bloat.
Covers addition, reading, deletion, movement, search, and listing. Missing an update/modify tool for resources or memory, which is a minor but notable gap.
Maintenance
Related MCP Connectors
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Persistent, outcome-grounded episodic memory for Claude. 14ms CPU retrieval, no GPU, no vector DB.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceLong-term memory MCP server for Claude Code with SQLite FTS5 full-text search, BM25 ranking, access tracking, and upsert deduplication. Zero config via npx.63 npmMIT
- AlicenseAqualityDmaintenancePersistent memory + FTS5 full-text search for Claude Code conversation history. Indexes ~/.claude/projects/ JSONL into SQLite, exposes 10 MCP tools (store/recall/search memories, browse sessions, get summaries) plus prompts. Includes a web UI for visual exploration10106 npm98MIT
- AlicenseNot gradedqualityDmaintenanceMCP Memory Server for Claude Code that provides persistent context across sessions using semantic search (RAG).Apache 2.0
- AlicenseAqualityCmaintenanceLocal-first memory for Claude Code and any MCP client: hybrid vector + keyword search and a bi-temporal knowledge graph in one SQLite file. Local embeddings, no API key, $0/token.51175 npm2PolyForm Noncommercial 1.0.0