peaka-mcp-server

Name: peaka-mcp-server
Author: peakacom

@peakacom

Repository

About peaka-mcp-server

MCP Server Implementation for Peaka

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "peaka": {
      "command": "npx",
      "args": [
        "-y",
        "@peaka/mcp-server-peaka@latest"
      ],
      "env": {
        "PEAKA_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Tools

List all projects accessible with the current API key. For Partner API keys, enumerates projects across all organizations and workspaces. For Project API keys, returns the single project bound to the key.

Query question/sql pairs from Peaka's golden sql vector store. If an existing query matches the user's question, it can be reused directly.

Runs the given sql query on Peaka.

Get metadata for all catalogs, schemas, and tables in the Peaka project in a single call. Optionally filter by `catalogId` and/or `schemaName`.

List all available catalogs in the Peaka project. Returns catalog names, types, and connection info.

List all available schemas for a given catalog in the Peaka project.

List all available tables for a given catalog and schema in the Peaka project.

List all columns for a given table in the Peaka project. Returns column names, data types, and constraints.

Get table relationships (foreign keys) for a catalog. Useful for constructing accurate JOINs.

Get column-level statistics for a table, including distinct-value fractions per column.

Create a cache for a table in the Peaka project. Caching a table improves query performance by storing the data locally.

Create caches for multiple tables in a single call. Preferred over repeated `peaka_create_cache` calls.

Get all cache statuses for tables in the Peaka project, including current caching state, execution history, and progress.

Trigger a full refresh on an existing cache.

Trigger an incremental update on an existing cache, fetching only new or changed rows.

Update cache settings (schedules) on an existing cache. Replaces both schedules entirely each call.

Delete an existing cache; the underlying table is not affected.

List all saved queries in the Peaka project. Returns query names, SQL content, and whether they are plain or materialized.

Read a single saved query by its ID. Returns the full query object including SQL, type, and the materialized-query refresh schedule.

Execute a saved query by its ID in the Peaka project.

Create a named, saved query in the project's semantic layer. Returns the created query including its ID. For materialized queries, accepts an optional `schedule` to set the auto-refresh cadence — `{type: "interval", repeatDuration: "PT6H"}`, `{type: "cron", cronExpression: "0 0 * * *", timezone: "UTC"}`, or `{type: "none"}` to disable.

Update an existing saved query's display name, SQL body, and/or auto-refresh `schedule` (interval, cron, or `{type: "none"}` to disable; materialized queries only).

Delete a saved query from the Peaka project.

Trigger a refresh on a materialized saved query. Use `peaka_list_queries` to find query IDs whose `queryType` is `MATERIALIZED`.

Inspect the auto-refresh state of materialized queries: last refresh status, last/next scheduled execution, and schedule settings. Pass a `queryId` for a single query or omit it to list all.

List all data source connections in the Peaka project, including each connection's id, name, and type.

Get connection-specific configuration detail for a data source connection.

Create a semantic catalog in the Peaka project. A semantic catalog groups semantic tables (saved queries surfaced as queryable tables) under a single namespace.

Create a semantic table inside a semantic catalog, backed by a saved query. Requires `catalogId`, `schemaName`, `tableName`, and `queryId`.

Delete a semantic table from a semantic catalog. The underlying saved query is not affected.

Refresh project metadata for a specific catalog. Long-running; triggers the refresh and polls for completion.

Check the current status of a metadata refresh job for a specific catalog.

Overview

What is peaka-mcp-server?

peaka-mcp-server is a Model Context Protocol (MCP) server that gives LLMs access to Peaka's text2SQL capabilities. It enables AI agents to inspect database schemas and execute SQL queries on Peaka projects.

How to use peaka-mcp-server?

Install by adding a configuration entry to your MCP client's config file (e.g., Claude Desktop's claude_desktop_config.json). Run the server via npx -y @peaka/mcp-server-peaka@latest and set the PEAKA_API_KEY environment variable. For packaged installation, run npm run pack to produce a .mcpb bundle and install it as a Claude Desktop extension.

Key features of peaka-mcp-server

List and manage Peaka projects and connections
Inspect database schemas, tables, and columns
Execute raw SQL queries via Peaka
Query and create golden question/SQL pairs
Manage table caches (create, refresh, update, delete)
Create and manage saved queries and semantic catalogs

Use cases of peaka-mcp-server

LLM agents exploring and querying a Peaka project’s schema
Automating SQL query generation from natural language questions
Managing cache policies to improve query performance
Building and maintaining semantic layers with saved queries
Refreshing stale project metadata for up-to-date schema info

FAQ from peaka-mcp-server

What does peaka-mcp-server do?

It provides MCP tools that let LLMs list projects, inspect schemas, execute SQL queries, and manage caches and saved queries on Peaka projects.

How is peaka-mcp-server authenticated?

Set the PEAKA_API_KEY environment variable with a valid Peaka API key (either Partner or Project key). See Peaka documentation for generating API keys.

What are the runtime dependencies?

Node.js and npm are required to run the server via npx. The server is published as an npm package @peaka/mcp-server-peaka.

Where does the data live and how is it accessed?

All data resides within the configured Peaka project(s). The server communicates with Peaka’s partner API (default: https://partner.peaka.studio/api/v1) and does not store any data locally.

What transport does peaka-mcp-server use?

The server runs as a subprocess using stdio transport, as is standard for MCP servers invoked via npx. It also supports MCP’s HTTP streaming mode (not described in detail in the README).