# Cosmos Semantic

> Cosmos Semantic is an open-source MCP server for analytics and data. Governed metrics, rules and a glossary for agents to query instead of guessing SQL. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, Web
- **Website:** https://wiliamrosa.github.io/cosmos-semantic-platform/
- **Repository:** https://github.com/wiliamrosa/cosmos-semantic-platform
- **MCP Registry name:** io.github.WiliamRosa/cosmos-semantic
- **Categories:** analytics and data, databases
- **Listing updated:** 2026-11-14

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## 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

- [Agent-Native Analytics](https://ai-powered.com/mcp/agent-native-analytics): Agent-Native Analytics is an open-source MCP server for analytics and data.
- [Google Ads + Meta Ads + SEO/GEO MCP](https://ai-powered.com/mcp/google-ads-meta-ads-seo-geo-mcp): Google Ads + Meta Ads + SEO/GEO MCP is a freemium MCP server for marketing and seo.
- [Tapetide - Indian Stock Market MCP](https://ai-powered.com/mcp/tapetide-indian-stock-market-mcp): Tapetide - Indian Stock Market MCP is a freemium MCP server for finance and payments.
- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [World Monitor](https://ai-powered.com/mcp/world-monitor): World Monitor is a freemium MCP server for analytics and data.
- [CompanyData](https://ai-powered.com/mcp/companydata): CompanyData is a paid MCP server for analytics and data.
- [ChartAnt](https://ai-powered.com/mcp/chartant): ChartAnt is a freemium MCP server for design and media.
- [Quantivex Research](https://ai-powered.com/mcp/quantivex-research): Quantivex Research is a free MCP server for finance and payments.

---
Source: https://ai-powered.com/mcp/cosmos-semantic
