Skip to main content
Glama

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 uvx for 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 plugin marketplace add samelie/arcana-mcp
claude plugin install arcana-mcp

This 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-mcp

Add 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

arcana_add_resource

Index a file or directory into the DB

arcana_add_memory

Store a memory entry with embedding

arcana_search

Hybrid semantic + FTS5 search (best default)

arcana_find

Pure semantic (cosine similarity) search

arcana_grep

Keyword/regex search via FTS5

arcana_read

Read full content of a resource

arcana_ls

List direct children at a URI

arcana_tree

Show recursive tree at a URI

arcana_stat

Get metadata + chunk count for a resource

arcana_rm

Remove a resource (with optional recursive)

arcana_mkdir

Create a directory at a URI

arcana_mv

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.

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

ARCANA_DB_PATH

~/.arcana/context.db

SQLite database path

ARCANA_MODEL_CACHE

~/.arcana/models

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 segments

  • MCP 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.0

The script will:

  1. Validate you're on main with a clean tree

  2. Optionally bump pyproject.toml and commit

  3. Wait for the monorepo sync workflow to push to samelie/arcana-mcp

  4. Verify the remote version matches

  5. Create a GitHub release (v0.x.x) which triggers the PyPI publish workflow

License

MIT

Available Tools

12 tools
arcana_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_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

    A3.7/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool has a distinct purpose: memory vs resource addition, different search modes (semantic, keyword, hybrid), and clear navigation vs content operations. No ambiguity.

    Naming Consistency5/5

    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.

    Tool Count5/5

    12 tools is well-scoped for a hierarchical resource and memory system, covering CRUD, navigation, search, and metadata retrieval without bloat.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Long-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 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Persistent 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 exploration
      10
      106 npm
      98
      MIT