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: claude-memory-fts

Install

Claude Code Plugin (recommended)

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

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

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