mcp-canon

Universal MCP knowledge server for LLM agents, powered by local RAG.

Use Canon to provide domain-specific best practices and playbooks across software engineering, marketing, video editing, and other knowledge areas.

Typical workflows:

• Find the most suitable guide for a task
• Retrieve concise best-practice snippets
• Read full guides for deeper execution context

---

Quick Start

<details> <summary><b>Install in Cursor</b></summary>

Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server

Pasting the following configuration into your Cursor ~/.cursor/mcp.json file is the recommended approach. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more info.

Cursor Local Connection

{
  "mcpServers": {
    "canon": {
      "command": "uvx",
      "args": ["mcp-canon"]
    }
  }
}

Cursor Local Connection With Custom Database

{
  "mcpServers": {
    "canon": {
      "command": "uvx",
      "args": ["mcp-canon"],
      "env": {
        "CANON_DB_PATH": "/path/to/my-db"
      }
    }
  }
}

Cursor Remote Server Connection

{
  "mcpServers": {
    "canon": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

</details>

<details> <summary><b>Install in Claude Code</b></summary>

Run this command. See Claude Code MCP docs for more info.

Claude Code Local Connection

claude mcp add --scope user canon -- uvx mcp-canon

Cursor Local Connection With Custom Database

claude mcp add --scope user -e CANON_DB_PATH=/path/to/my-db canon -- uvx mcp-canon

Claude Code Remote Server Connection

claude mcp add --scope user --transport http canon http://localhost:8080/mcp

Remove --scope user to install for the current project only.

</details>

<details> <summary><b>Install in Opencode</b></summary>

Add this to your Opencode configuration file. See Opencode MCP docs for more info.

Opencode Local Connection

{
  "mcp": {
    "canon": {
      "type": "local",
      "command": ["uvx", "mcp-canon"],
      "enabled": true
    }
  }
}

Opencode Local Connection With Custom Database

{
  "mcp": {
    "canon": {
      "type": "local",
      "command": ["uvx", "mcp-canon"],
      "enabled": true,
      "environment": {
        "CANON_DB_PATH": "/path/to/my-db"
      }
    }
  }
}

Opencode Remote Server Connection

"mcp": {
  "context7": {
    "type": "remote",
    "url": "http://localhost:8080/mcp",
    "enabled": true
  }
}

</details>

<details> <summary><b>Install in Gemini CLI</b></summary>

Run this command. See Gemini CLI MCP docs for more info.

Gemini CLI Local Connection

gemini mcp add --scope user canon uvx mcp-canon

Gemini CLI Local Connection With Custom Database

gemini mcp add --scope user -e CANON_DB_PATH=/path/to/my-db canon uvx mcp-canon

Gemini CLI Remote Server Connection

gemini mcp add --scope user --transport http canon http://localhost:8080/mcp

Remove --scope user to install for the current project only.

</details>

<details> <summary><b>Install in Google Antigravity</b></summary>

Go to the agent panel and open: ... -> MCP Servers -> Manage MCP Servers -> View raw config. Add this to your mcp_config.json file. See Google Antigravity MCP docs for more info.

Google Antigravity Local Connection

{
  "mcpServers": {
    "canon": {
      "command": "uvx",
      "args": ["mcp-canon"]
    }
  }
}

Google Antigravity Local Connection With Custom Database

{
  "mcpServers": {
    "canon": {
      "command": "uvx",
      "args": ["mcp-canon"],
      "env": {
        "CANON_DB_PATH": "/path/to/my-db"
      }
    }
  }
}

</details>

---

Create and index your own guides

Complete workflow from installation to running with your own domain guides.

Step 1: Install with indexing support

pip install "mcp-canon[indexing]"

Step 2: Create library structure

my-library/
├── engineering/
│   └── python-fastapi-guide/
│       ├── INDEX.md      # Required: metadata
│       └── GUIDE.md      # Content
├── marketing/
│   └── launch-playbook/
│       ├── INDEX.md
│       └── GUIDE.md
└── video-editing/
    └── shorts-workflow/
        └── INDEX.md      # Can reference external URL

Step 3: Create guides

Step 4: Index your library

# Index to custom location
canon index --library ./my-library --output /path/to/my-db

# Validate frontmatter before indexing (optional)
canon validate --library ./my-library

Running as HTTP server

For remote access or multi-client scenarios, run Canon as an HTTP server. This is useful when multiple agents or teams share one cross-domain knowledge base.

Step 1: Install with HTTP support

pip install "mcp-canon[http]"

Step 2: Start the server

# Default port 8080
canon serve

# Custom port and host
canon serve --port 3000 --host 0.0.0.0

# With custom database
CANON_DB_PATH=/path/to/db canon serve --port 8080

Step 3: Configure MCP client

{
  "mcpServers": {
    "canon": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Environment Variables

Variable	Description	Default
CANON_DB_PATH	Path to custom database	Bundled DB
CANON_EMBEDDING_MODEL	Fastembed model name (supported models)	nomic-ai/nomic-embed-text-v1.5-Q
CANON_EMBEDDING_DIM	Embedding vector dimensions (must match model)	768
CANON_FASTEMBED_THREADS	ONNX runtime threads for FastEmbed (lower = less RAM, slower)	auto
CANON_FASTEMBED_BATCH_SIZE	Embedding batch size during indexing (lower = less RAM, slower)	256
CANON_FASTEMBED_PARALLEL	FastEmbed data-parallel workers (>1 increases RAM usage)	disabled
CANON_LOG_LEVEL	Log level (DEBUG, INFO, WARNING, ERROR)	INFO
CANON_LOG_JSON	Output logs in JSON format	false

Note: Changing CANON_EMBEDDING_MODEL or CANON_EMBEDDING_DIM requires a full reindex: canon index --library ./library

Change embedding model and dimensions

Internal constants EMBEDDING_MODEL_NAME and EMBEDDING_DIM are configured via:

• CANON_EMBEDDING_MODEL
• CANON_EMBEDDING_DIM

Example (using BAAI/bge-small-en-v1.5, 384 dims):

CANON_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5 \
CANON_EMBEDDING_DIM=384 \
canon index --library ./library --output ./my-db

Where to find available models:

• FastEmbed supported models: https://qdrant.github.io/fastembed/examples/Supported_Models/
• FastEmbed model card and usage notes: https://qdrant.github.io/fastembed/

Important:

• CANON_EMBEDDING_DIM must match the selected model output size.
• After changing model or dimension, rebuild the index before running search/server commands.

---

MCP Tools

Tool	Description
search_best_practices	Semantic search for best practices in any domain (optionally scoped by guide_id)
search_suitable_guides	Find guides that match a task description across domains
read_full_guide	Get complete guide content for full context

---

CLI Commands

# Indexing
canon index --library ./library           # Index guides from any domain (creates new DB)
canon index --library ./lib --append      # Add to existing database
canon validate --library ./library        # Validate frontmatter

# Server
canon serve --port 8080                   # Start HTTP server (requires [http])

# Info
canon list                                # List indexed guides
canon info                                # Show database info

---

License

MIT