ClawQL

ClawQL is an MCP server for API discovery and execution with a token-efficient search -> execute workflow over OpenAPI, Google Discovery, and optional native GraphQL and gRPC sources (see CLAWQL_GRAPHQL_URL / CLAWQL_GRAPHQL_SOURCES / CLAWQL_GRPC_SOURCES in .env.example and ADR 0002). GraphQL-only vendors (e.g. Linear) need no OpenAPI spec: use CLAWQL_PROVIDER=linear (bundled SDL under providers/linear/ + LINEAR_API_KEY), or point CLAWQL_GRAPHQL_URL at their HTTP endpoint and auth headers, or load search from CLAWQL_GRAPHQL_SCHEMA_PATH / CLAWQL_GRAPHQL_INTROSPECTION_PATH (or per-source schemaPath / introspectionPath) when upstream introspection is disabled — without CLAWQL_SPEC_* / CLAWQL_PROVIDER, the default bundled REST specs are not loaded.

What You Get

Feature tiers (aligned with the architecture diagram — details in docs/readme/configuration.md):

• ClawQL Core (always on — no opt-out): search, execute, audit, cache — same band in the diagram; ring-buffer semantics for audit and LRU semantics for cache in docs/mcp/enterprise-mcp-tools.md and docs/mcp/cache-tool.md.
• Default on — opt out: memory_ingest / memory_recall, and the document stack (ingest_external_knowledge, plus knowledge_search_onyx when CLAWQL_ENABLE_ONYX=1). Use CLAWQL_ENABLE_MEMORY=0 or CLAWQL_ENABLE_DOCUMENTS=0 to hide; vault path still required for real disk I/O on memory / ingest.
• Default off — opt in: sandbox_exec (CLAWQL_ENABLE_SANDBOX=1), schedule, notify, knowledge_search_onyx (needs CLAWQL_ENABLE_ONYX=1 and documents on), ouroboros_* — see docs/mcp/mcp-tools.md. When enabled, CLAWQL_SANDBOX_BACKEND: omit = bridge; auto = Seatbelt → Docker → bridge.
• Stdio and HTTP MCP server modes
• Bundled provider specs for offline lookup and multi-provider workflows

Primary package: clawql-mcp
Repo: https://github.com/danielsmithdevelopment/ClawQL

Container images on GHCR (Docker / Helm)

Prebuilt images live on GitHub Container Registry under ghcr.io/danielsmithdevelopment/ (clawql-mcp, clawql-website, clawql-dashboard, clawql-panguard-mcp-bridge). They are supposed to be public so anyone can docker pull without credentials and Kubernetes defaults (Kyverno) can verify signatures. If docker pull returns denied, the registry package is still private — see docker/README.md § GHCR visibility (checklist + make ghcr-packages-public for maintainers).

Quick Start

Install:

npm install clawql-mcp

Run with bundled providers:

CLAWQL_PROVIDER=all-providers npx clawql-mcp

Then configure your MCP client (Cursor/Claude Desktop) to connect.

Documentation Map

Top-level docs index: docs/README.md

Start here

• Getting started: docs/readme/getting-started.md
• Configuration and env precedence: docs/readme/configuration.md
• Deployment and client config: docs/readme/deployment.md (Kubernetes list links docs/deployment/docker-desktop-istio-observability.md for Istio + Prometheus/Grafana/Tempo/Kiali/OTel on Docker Desktop)
• Benchmarks and case studies: docs/readme/benchmarks.md
• Development notes: docs/readme/development.md
• Tool workflow skills: docs/skills/README.md

Core references

• MCP tools and examples: docs/mcp/mcp-tools.md
• Workflow recipes: docs/recipes/README.md
• Memory and vault workflows: docs/memory/memory-obsidian.md
• Cache tool: docs/mcp/cache-tool.md
• Enterprise MCP notes (audit threat model, future metrics/governance): docs/mcp/enterprise-mcp-tools.md
• Slack notify tool: docs/mcp/notify-tool.md
• Onyx knowledge tool: docs/mcp/onyx-knowledge-tool.md
• Ouroboros package and integration: docs/ouroboros/clawql-ouroboros.md

Deployments

• Docker: docker/README.md
• Cloud Run: docs/deployment/deploy-cloud-run.md
• Kubernetes: docs/deployment/deploy-k8s.md
• Helm chart: docs/deployment/helm.md
• Tailscale / Headscale (beginner guide): docs/deployment/tailscale-and-headscale-for-clawql.md (website /tailscale)
• Headscale runbook + ACL starter: docs/deployment/headscale-tailnet.md, docs/deployment/headscale-acls-clawql.hujson

Security and supply chain

• Security overview and shipped controls: docs/security/README.md
• Golden image pipeline (CI → scan → push → sign → Kyverno enforcement): docs/security/golden-image-pipeline.md
• Defense in depth reference: docs/security/clawql-security-defense-in-depth.md
• Engineering deliverables matrix (shipped/partial/planned): docs/security/clawql-security-defense-deliverables.md
• Docker SBOM/sign/scan operator notes: docker/README.md
• npm publish hardening (pack → scan → publish, provenance): docs/security/npm-supply-chain.md
• Deploy-time image signature enforcement (admission / Kyverno): docs/security/image-signature-enforcement.md

Providers and specs

• Provider matrix and presets: providers/README.md
• Google Discovery helpers: docs/providers/google-apis-lookup.md

Architecture (Short Version)

1. Agent calls search to discover relevant operations without loading entire specs into prompt context.
2. Agent calls execute with operation details.
3. For OpenAPI/Discovery operations: in single-spec mode, ClawQL prefers an internal OpenAPI-to-GraphQL path (REST fallback on failure); in multi-spec mode, execute uses REST per owning spec.
4. For native operations (when configured): execute calls HTTP GraphQL or gRPC unary directly — same search index, routed by operation metadata — see ADR 0002.

Notes

• Core (search, execute, audit, cache) has no opt-out — no CLAWQL_ENABLE_* gate for those tools.
• A writable CLAWQL_OBSIDIAN_VAULT_PATH is required to read/write the vault for memory_* and bulk ingest_external_knowledge.
• For full environment variable details, see .env.example and docs/mcp/mcp-tools.md.