Skip to content
MCP server

Cosmos Semantic

Governed metrics, rules and a glossary for agents to query instead of guessing SQL

Runs locallyStatus and history
Pricing
Open source
Platforms
CLI, self-hosted, Web
Runs
Locally
Version
0.3.0
Listing updated
3 days ago

About Cosmos Semantic

Cosmos Semantic is an open-source MCP server for analytics and data. It runs locally on your machine and is started by your AI client.

The idea behind it is that "revenue" or "active customer" should be defined once, with an owner and tests, rather than re-invented by each agent that writes SQL. Metrics, versioned business rules and a bilingual SKOS glossary live in YAML that follows dbt Semantic Layer vocabulary, and a JSON Schema ships with it.

Over MCP an agent finds the concept, requests a governed metric and gets deterministic SQL back. Each answer carries its evidence: the expanded formula, the rules and row filters applied, a reference date and hashes. A replay command shows whether a number has changed since and why, and a reconciliation step compares a governed metric with a team's existing legacy SQL and names the likely cause of each gap.

The README says the same model returns the same number on Databricks, Snowflake, Oracle, SQL Server, Postgres, MySQL, MariaDB and DuckDB, and that personal data never reaches the agent. It imports from dbt, Power BI, Cube and Apache Ossie. The server runs over stdio from the PyPI package and needs an API key whose user context feeds the row filters.

Install

Run in a terminal

claude mcp add cosmos-semantic --env COSMOS_API_KEY='<COSMOS_API_KEY>' -- uvx cosmos-semantic

Add to claude_desktop_config.json

{
  "mcpServers": {
    "cosmos-semantic": {
      "command": "uvx",
      "args": [
        "cosmos-semantic"
      ],
      "env": {
        "COSMOS_API_KEY": "<COSMOS_API_KEY>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "cosmos-semantic": {
      "command": "uvx",
      "args": [
        "cosmos-semantic"
      ],
      "env": {
        "COSMOS_API_KEY": "<COSMOS_API_KEY>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "cosmos-semantic": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "cosmos-semantic"
      ],
      "env": {
        "COSMOS_API_KEY": "<COSMOS_API_KEY>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "cosmos-semantic": {
      "command": "uvx",
      "args": [
        "cosmos-semantic"
      ],
      "env": {
        "COSMOS_API_KEY": "<COSMOS_API_KEY>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "cosmos-semantic": {
      "command": "uvx",
      "args": [
        "cosmos-semantic"
      ],
      "env": {
        "COSMOS_API_KEY": "<COSMOS_API_KEY>"
      }
    }
  }
}

Configuration

  • COSMOS_API_KEYThe caller's key; its user context feeds the model's row filtersRequired
  • COSMOS_DEV_API_KEYSYAML file with development keys (local use); production uses an OIDC provider

What it does

Governed metrics
Metrics are defined once in YAML and compiled to deterministic SQL for each supported database.
Evidence on every answer
Answers include the formula, rules, row filters, reference date and hashes so a number can be explained.
Replay and reconciliation
A replay command shows if a number moved; reconciliation compares it with legacy SQL and suggests causes.
Business ontology
A bilingual SKOS glossary, versioned rules with owners and tests, and a knowledge graph of teams and systems.
Import from other tools
Models can be imported from dbt, Power BI, Cube and Apache Ossie.
Read-only console
A web console shows model health, process graphs, the catalogue and audited answers.

Good for

  • Give an analytics agent one agreed definition of revenue or active customer
  • Prove to auditors how a reported number was calculated
  • Find out why a dashboard number differs from a legacy report
  • Keep personal data out of AI agent answers while still serving metrics
  • Document business rules with owners and tests

Pricing

Open source

Apache 2.0 core within an open-core model

Prices change. Check wiliamrosa.github.io before you buy.

Cosmos Semantic FAQ

Which databases does it support?

The README lists Databricks, Snowflake, Oracle, SQL Server, Postgres, MySQL, MariaDB and DuckDB, checked by the test suite on every change.

How is it licensed?

The core is Apache 2.0 within an open-core model.

What does the MCP server need to run?

A COSMOS_API_KEY for the caller, whose user context feeds the model's row filters. Development keys can come from a YAML file; production uses an OIDC provider.

Can I try it without a warehouse?

Yes. The quickstart builds a demo on a local DuckDB file with sample data and runs a governed query with evidence.

Is Cosmos Semantic free?

Yes. Cosmos Semantic is open source, so you can use and self-host it for free.

How do I add Cosmos Semantic to Claude Code?

Run this command in your terminal: claude mcp add cosmos-semantic --env COSMOS_API_KEY='<COSMOS_API_KEY>' -- uvx cosmos-semantic

What are the best alternatives to Cosmos Semantic?

The closest alternatives to Cosmos Semantic are Agent-Native Analytics, Google Ads + Meta Ads + SEO/GEO MCP, Tapetide - Indian Stock Market MCP, Midplane and World Monitor.

Alternatives to Cosmos Semantic

  1. Open-source analytics app where an AI agent builds charts and dashboards from your data

    • Remote
    • Open source
    • 7.7K GitHub stars
    • Analytics and data
  2. Hosted MCP connector for managing Google Ads, Meta Ads, GA4 and Search Console from chat

    • 8 tools
    • Remote
    • Freemium
    • 8.1K GitHub stars
    • Marketing and SEO
  3. Indian NSE and BSE stock market data for AI assistants through 48 MCP tools

    • 17 tools
    • Remote
    • Freemium
    • 150 GitHub stars
    • Finance and payments
  4. Midplane

    MCP server

    Postgres gateway for AI agents with table grants, column masking and approval for writes

    Runs locally
    • Open source
    • 5 GitHub stars
    • Databases
  5. World Monitor

    MCP server

    Live geopolitical intelligence dashboard with an API and MCP server for agents

    • Remote
    • Freemium
    • Analytics and data
  6. CompanyData

    MCP server

    Search and enrich company records from official registers via the CompanyData API

    • 3 tools
    • Remote
    • Paid
    • 3 GitHub stars
    • Analytics and data