arca-mcp
m0nochr0me/arca-mcp
Arca Memory Core - MCP Server for compact memories
Instalação
npx convez-ai m0nochr0me/arca-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Arca MCP
A Model Context Protocol (MCP) server providing semantic memory storage and retrieval via vector embeddings. Built with FastAPI + FastMCP, using LanceDB for vector storage and Google Gemini for embedding generation.
Features
- Semantic Search — Store and retrieve memories using natural language queries powered by vector similarity search
- Dual Access — MCP tools for AI agents + REST API for programmatic integrations
- Knowledge Graph — Connect memories with directed, labelled edges and traverse them
- Multi-Tenant Isolation — Namespace-scoped operations via
X-NamespaceHTTP header - Bucket Organization — Group memories into logical buckets for structured storage
- JSON Canvas Export — Render a bucket's memories and connections as a JSON Canvas document
- Document Ingestion (optional add-on) — Chunk and store whole documents (txt/md, plus PDF/DOCX/HTML/EPUB/FB2 via per-format extras) through the
arca-ingestpackage (uv sync --extra ingest), exposed asPOST /v1/ingestand thememory/ingesttool - Embedding Caching — Redis-backed cache for generated embeddings to minimize API calls
- Bearer Token Auth — Constant-time token verification for secure access
Prerequisites
- Python 3.14+
- UV package manager
- Redis
- Google API key (for Gemini embeddings)
Quick Start
# Clone the repository
git clone https://github.com/m0nochr0me/arca-mcp.git
cd arca-mcp
# Install dependencies
uv sync --locked
# Configure environment — create a .env with at least the required secrets
cat > .env <<'EOF'
ARCA_APP_AUTH_KEY=your-secret-bearer-token
ARCA_GOOGLE_API_KEY=your-google-api-key
EOF
# Run the server
python -m app
The server starts on http://0.0.0.0:4201 by default, with the MCP interface at /app/mcp and the REST API at /v1. See Configuration for all available settings.
Docker
# Build (core, no add-ons)
docker build -t arca-mcp .
# Build with the document-ingestion add-on (txt/md only)
docker build --build-arg ARCA_INSTALL_EXTRAS=ingest -t arca-mcp .
# Build with ingestion + every format loader (PDF/DOCX/HTML/EPUB/FB2)
docker build --build-arg ARCA_INSTALL_EXTRAS=ingest-all -t arca-mcp .
# Run
docker run -p 4201:4201 \
-e ARCA_APP_AUTH_KEY=your-secret-key \
-e ARCA_GOOGLE_API_KEY=your-google-api-key \
-e ARCA_REDIS_HOST=host.docker.internal \
arca-mcp
The Docker image uses Python 3.14 slim with UV for dependency management. Mount a volume at ARCA_VECTOR_STORE_PATH (default ./lancedb) to persist data across container restarts.
ARCA_INSTALL_EXTRAS selects an optional extra to install at build time: ingest for the base add-on (txt/md), or ingest-all for the add-on plus all format parsers. The build arg takes a single extra name — not a pkg[extra] specifier like ingest[all].
MCP Client Configuration
Example .mcp.json for connecting an MCP client (e.g., Claude Code):
{
"mcpServers": {
"arca_memory": {
"type": "http",
"url": "http://localhost:4201/app/mcp",
"headers": {
"Authorization": "Bearer <your-auth-key>",
"X-namespace": "my_namespace"
}
}
}
}
<your-auth-key> must match ARCA_APP_AUTH_KEY. The X-namespace header scopes all operations to a tenant (defaults to "default" if omitted).
Documentation
In-depth reference material lives in doc/:
- Configuration — all
ARCA_environment variables and their defaults - MCP Tools — the
memory/*tool reference (add, get, graph traversal, …) - REST API —
/v1/*endpoint reference withcurlexamples - Architecture — request flow, module layout, key patterns, tech stack
License
See LICENSE.