coral README

The project's README from github.com/withcoral/coral. As one markdown file: README.md.

Coral cover

CI Release License Docs Discord Ask DeepWiki

Coral is a single query interface for agents calling data source APIs.

Agents make fewer, more precise tool calls with Coral than they do with per-source MCP servers, CLI tools, or API wrappers. For agent read tasks, SQL has a structural advantage when a question needs more than one API call: it avoids paginating through large results, returns tabular rows instead of sprawling JSON, brings back only the columns you asked for, and correlates across sources in a single statement.

Everything is local: your data, credentials, and usage history never leave your machine.

Download Coral for macOS Download Coral for Linux Download Coral for Windows

Coral ships as a desktop app on macOS, Linux, and Windows. For servers and automation, use the CLI.

Get started

  1. Install Coral. Use a download above, or see all installation options.
  2. Add your sources. Connect GitHub, Slack, Datadog, and other bundled sources from the sources page. Coral only fetches data from sources you connect.
  3. Connect your agents over MCP. The app exposes an MCP server over stdio. Point Claude Code, Codex, Cursor, or VS Code at it — see Use Coral over MCP.

Then ask your agent a question about your data:

Coral answering a data question in Claude

Why Coral

Most agent workflows access company data one tool at a time. That works, but it tends to create:

Coral gives agents one query interface instead:

We benchmarked Coral against direct provider MCPs (Datadog, Sentry, Linear, Slack, and GitHub) for a diverse set of 82 real-world AI tasks using Claude Opus 4.6. Key findings:

  1. Widespread impact on performance. Across all tasks, Claude was 20% more accurate and 2x more cost efficient using Coral than using direct provider MCPs. With Coral, Claude also had 42% lower latency.

  2. Highest impact on coding agent tasks. Across the more complex tasks that typify coding agent workloads (multi-hop, higher post-processing), Claude was 31% more accurate and 3.4x more cost efficient with Coral.

  3. More neutral impact on simpler tasks. For simpler AI tasks, such as raw fact retrieval from knowledge bases, the results were closer, with Claude 6% more accurate and 2% more cost efficient with Coral.

Full benchmark report.

How Coral works

Coral sits between your agents and your data sources: your agents write SQL, and Coral translates it into API calls or file reads, then returns a single result set.

graph LR
    Agent["You / your agent"] -->|SQL query| Coral["Coral (local)"]
    Coral -->|Result rows| Agent

    subgraph Sources["Installed sources"]
        GH["github source<br/>(github.* tables)"]
        LN["linear source<br/>(linear.* tables)"]
        FS["file source<br/>(your_files.* tables)"]
    end

    Coral --> GH
    Coral --> LN
    Coral --> FS

    subgraph Backing["Backing systems"]
        GHAPI["GitHub API"]
        LNAPI["Linear API"]
        Disk["Local files"]
    end

    GH -.->|PAT / gh auth token| GHAPI
    LN -.->|Personal API key| LNAPI
    FS -.->|File path| Disk

Sources. A source spec is a YAML file that declares how to reach an API or local dataset and which tables and columns it exposes. A source is that spec plus the credentials and variables you configured for it. When you run coral source add github, Coral installs the github source and exposes it at query time as the github SQL schema, so tables like github.issues and github.pulls become queryable. Start with the bundled sources or write your own.

Joins across sources. Because every source appears as SQL tables, you can JOIN across them in one statement, and Coral executes the join locally after fetching each side from its backing API or files. For example, to see which Linear issues are tracking open GitHub pull requests:

SELECT a.issue_identifier, a.url, p.state
FROM linear.attachments a
JOIN github.pulls p ON p.html_url = a.url
WHERE p.owner = 'withcoral' AND p.repo = 'coral'

Authentication. On coral source add, Coral reads variables and secrets from matching environment variables, or prompts for them when you pass --interactive. These values are stored locally and used only at query time; credentials never leave your machine.

Built for production. Coral is a read layer by design. For read tasks, SQL outperforms per-source tool calls when complexity outgrows a single API call: Coral handles pagination, returns tabular rows instead of sprawling JSON, and lets the query pick just the columns it needs. Query pushdown and caching keep things responsive and cut unnecessary API traffic.

For a deeper understanding of the internals, see the architecture page.

Sources

Coral bundles popular data sources — Datadog, GitHub, Linear, Sentry, Slack, Stripe, and more — plus local JSONL and Parquet files. Run coral source discover to see what your build bundles.

Many more community source specs live in this repo under sources/community and import with coral source add --file. Community sources do not appear in coral source discover, and coral source add <name> installs bundled sources only.

If neither covers what you need, write your own source spec, or tell us which source to add.

CLI quickstart

This walks the CLI path end to end, from a fresh install to your first SQL query. For the desktop app, see Get started above. If you prefer an interactive wizard, run coral onboard, which guides you through everything covered below.

1. Install Coral

On macOS:

brew install withcoral/tap/coral

Or on Linux:

curl -fsSL https://withcoral.com/install.sh | sh

Or on Windows 10/11 x86_64, download coral-x86_64-pc-windows-msvc.zip from the latest GitHub release and put coral.exe on your PATH.

See all install options.

2. Discover bundled sources

coral source discover

This lists the bundled sources available in your build.

3. Add a source

For example, add GitHub interactively:

coral source add --interactive github

Coral prompts for any required variables or secrets. For scripted setup, omit --interactive and provide each input as an environment variable of the same name, such as GITHUB_TOKEN=ghp_... coral source add github. Once connected, the source's data is available as SQL tables. To update a source's credentials later, run the same command again.

4. Query your data

Use coral.tables and coral.table_functions to see available query surfaces:

coral sql "SELECT schema_name, table_name FROM coral.tables ORDER BY 1, 2"
coral sql "SELECT schema_name, function_name FROM coral.table_functions ORDER BY 1, 2"

Assuming you've connected GitHub, try listing open issues for a repo:

coral sql "
  SELECT number, title, state, created_at
  FROM github.issues
  WHERE owner = 'withcoral' AND repo = 'coral' AND state = 'open'
  ORDER BY created_at DESC
  LIMIT 10
"

coral sql query demo

Next steps

Use Coral with an agent

Coral ships with a built-in MCP server that presents Coral to your agent as a read-only SQL database. Once you've added at least one source, wire Coral into your agent:

claude mcp add --scope user coral -- coral mcp-stdio   # Claude Code
codex mcp add coral -- coral mcp-stdio                 # Codex

For Cursor, VS Code, Claude Desktop, OpenCode, and manual config examples, see Use Coral over MCP.

Coral also publishes three skills that teach your agent the discovery-first SQL workflow: coral, coral-create-source-spec, and coral-review-source-spec.

npx skills add withcoral/skills

Once connected, ask your agent a question about your data. It should reach for search first to find the right schemas and tables, fall back to the coral.tables, coral.table_functions, and coral.columns metadata tables for catalog discovery, then answer with SQL over the sources you connected.

Local state

Coral stores local state in its platform-specific configuration directory.

You can override the config directory with:

export CORAL_CONFIG_DIR=/path/to/coral-config

Important files include:

Bundled source specs are not copied into the config directory. Coral resolves them from the current binary when you validate or query a bundled source, so upgrades pick up newer bundled manifests without re-adding the source.

Development

Install the local test runner once with Homebrew:

brew install cargo-nextest

Or install it with Cargo:

cargo install cargo-nextest --locked

Run the workspace validation gate from the repository root:

make rust-checks

Documentation

For setup guides, reference docs, and examples, visit withcoral.com/docs.

Community

Questions, ideas, and show-and-tell are welcome in our Discord or on GitHub issues.

Contributing

Contributions are welcome, especially bug fixes, tests, documentation improvements, source improvements, and user-facing usability improvements.

Please read CONTRIBUTING.md before opening a pull request.

Security

Please do not report security issues in public issues or pull requests. See SECURITY.md.

Licence

Coral is licensed under the Apache License 2.0. See LICENSE.

coral (withcoral/coral)

Searching Database…

4.9K ·GitHub
Coral
Что это такое?Coral — это единый интерфейс SQL-запросов, который позволяет ИИ-агентам и разработчикам одновременно запрашивать несколько живых источников данных: API, такие как GitHub, Slack, Datadog, Stripe и Sentry, а также локальные файлы JSONL/Parquet. Всё это работает через один слой SQL, без необходимости обращаться к отдельному MCP-серверу или обёртке API каждого источника.
Это база данных, которую нужно настраивать, или слой поверх моих существующих источников?Это не база данных со своим хранилищем. Coral — слой только для чтения: он переводит SQL в живые вызовы API или чтение файлов из подключённых источников и возвращает результаты как обычные табличные строки.
Как запустить это и подключить мои данные?Установите Coral как настольное приложение (macOS, Linux, Windows) или как CLI, затем выполните 'coral source add github' (или другой встроенный источник), чтобы подключить его. Coral запросит необходимые учётные данные в интерактивном режиме или возьмёт их из соответствующих переменных окружения.
Какие агенты для написания кода могут подключаться к Coral и нужны ли учётные данные для каждого источника?Coral предоставляет MCP-сервер через stdio, к которому могут подключаться Claude Code, Codex, Cursor и VS Code. Да, каждому источнику, например GitHub, Slack или Datadog, нужны свои учётные данные, которые настраиваются при его добавлении.
Могу ли я записывать данные обратно через Coral или доступ только для чтения?Coral по замыслу работает только на чтение. Он создан для запросов и сопоставления существующих данных из разных источников, а не для записи или изменения данных.
Покидают ли мои данные и учётные данные когда-нибудь мой компьютер?Нет. Всё работает локально: ваши данные, учётные данные и история использования остаются на вашем компьютере и никуда не отправляются.
Зачем использовать Coral вместо прямого подключения агентов к MCP-серверам отдельных источников?Прямые MCP-серверы отдельных источников создают слишком много вызовов инструментов, повторяют логику авторизации и постраничной навигации и плохо справляются с рассуждениями между источниками. Coral позволяет агенту написать один SQL-запрос, который объединяет данные из нескольких источников.
Насколько лучше Coral показал себя в бенчмарках?По сравнению с прямыми MCP-серверами провайдеров (Datadog, Sentry, Linear, Slack, GitHub) на 82 реальных задачах с Claude Opus 4.6 Coral оказался точнее на 20%, экономичнее по стоимости в 2 раза и имел на 42% меньшую задержку в целом. На сложных задачах в стиле агентов для написания кода точность выросла на 31%, а стоимость снизилась в 3,4 раза.
Можно ли подключать источники данных, которые не входят в комплект поставки?Да. Можно написать собственную спецификацию источника (YAML-файл, который описывает API или набор данных, а также его таблицы и столбцы) или взять спецификации от сообщества из папки 'sources/community' в репозитории.
Что делает 'coral search'?'coral search' находит нужные схемы и таблицы в метаданных каталога до того, как вы напишете SQL. Это помогает агентам понять, что можно запросить, не угадывая имена таблиц.
What are similar projects?headroom, Benzi, BrowserOS, graphicle, okf-agent-memory, leviathan, Agentlas-OS, github-mcp-server
Which topics is it in?yaml, vscode, github, sql, model-context-protocol, cursor, agentic-ai, local-first, benchmark, mcp-server, database, claude
Creator
withcoral
Size
45.4 MB
Stars
4.9K
Updated
CommitOct 16Releasev1.1.0Oct 15
Age
6mo
Commits · 90 Days