@shahid.la/cds-db-nlquery-mcp

MCP server for natural language queries against CDS db-layer entities (db/schema.cds).

Ask questions about your database in plain English. The server discovers your schema automatically, generates real SQL JOINs using CDS, and returns rows. No hardcoded queries, no SQL, no schema configuration. Bring your own LLM: Anthropic or OpenAI, or any OpenAI-compatible endpoint (Azure OpenAI, Groq, Ollama, local models, etc.).

Targets the db/ layer, not OData services. If your entities are exposed as OData services, use an MCP package that targets the service layer instead.

Read-only. This package only executes SELECT queries. No INSERT, UPDATE, or DELETE.

Prerequisites

• A CAP project with @sap/cds >= 7
• A configured CDS database (HANA Cloud, SQLite, PostgreSQL)
• An MCP client (Claude Code, Claude Desktop, or any MCP-compatible host)
• An API key for an LLM provider (see LLM provider below), used to translate your question into a query, not to answer it

Quick start

1. Install in your CAP project

npm install @shahid.la/cds-db-nlquery-mcp

2. Create .mcp.json in your CAP project root (same folder as package.json)

{
  "mcpServers": {
    "cds-db-nlquery": {
      "command": "npx",
      "args": ["-y", "@shahid.la/cds-db-nlquery-mcp"],
      "cwd": "/absolute/path/to/your/cap/project",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Set cwd to the absolute path of your CAP project root, where db/schema.cds lives. See LLM provider for using OpenAI, Gemini, or another provider instead.

npx -y re-resolves the package on every server start (from npm's cache once downloaded, not a fresh network fetch each time, but still an extra resolution step). If you've run npm install @shahid.la/cds-db-nlquery-mcp already, you can point "command" at the installed binary directly instead, node_modules/.bin/cds-db-nlquery-mcp, for a slightly more predictable startup, especially in production.

3. Open your project in Claude Code and ask a question

Which customers have a DTI ratio above 5?
Show me all open payments overdue by more than 30 days, include the borrower name.
List all loans in the MINING sector with the customer's current DTI ratio.

Example response: the server tells the client to render rows as a vertical field/value list, not a markdown table (real output, verified against a live deployment):

Found 3 customers with DTI above 5:

PARTNER    : 30100003
DTI_RATIO  : 7.20
BU_SORT1   : Domestic Customer AU 3

PARTNER    : 30100001
DTI_RATIO  : 5.80
BU_SORT1   : Domestic Customer AU 1

PARTNER    : 30100002
DTI_RATIO  : 5.40
BU_SORT1   : Domestic Customer AU 2

How it works

When you ask a question:

1. Your MCP client (e.g. Claude Code) calls the natural_language_query tool with your question.
2. The MCP server has already loaded your CDS schema at startup: entity names, columns, and associations. It sends this schema plus your question to the LLM provider you configured (Anthropic, OpenAI, or any OpenAI-compatible endpoint), which translates it into a structured query descriptor.
3. The server executes a single CDS query. CDS association paths (customer.BU_SORT1) generate real SQL JOINs, executed by your database, not by JavaScript. Scales to production data volumes.
4. Results come back to your MCP client, which formats and presents the answer.

The LLM call in step 2 is a small, cheap planning step (translating your question into JSON). It does not need a large or expensive model. A fast/cheap tier model is recommended.

Configuration

All configuration is via environment variables in the .mcp.json env block.

{
  "mcpServers": {
    "cds-db-nlquery": {
      "command": "npx",
      "args": ["-y", "@shahid.la/cds-db-nlquery-mcp"],
      "cwd": "/path/to/your/cap/project",
      "env": {
        "ANTH

... [View full README on GitHub](https://github.com/shahidla/cds-db-nlquery-mcp#readme)