Skip to main content
Glama
harbor-mcp-server

harbor-mcp-server

harbor-mcp-server

An MCP server that gives an AI agent access to a subscription business's database — without giving it the database.

Reads are parsed and allowlisted before they run. Personal data is masked on the way out. Writes require a preview and a confirmation token. Everything is written to an audit log the agent cannot read.

npx harbor-mcp-server

That is the whole setup — no native addon to compile, no database to provision. It ships with a seeded demo database of 140 customers, ~1,950 invoices, ~260 support tickets and 90 days of usage events, so there is nothing to configure before you can ask it a question.


Why this exists

"Let Claude query our database" is a two-line proof of concept and a genuinely hard production problem. The gap between them is not the SQL — it is everything you have to be sure of before you point a language model at a table containing real customers.

This server is the second thing, built small enough to read in one sitting.


Related MCP server: sql-explorer-mcp

What it refuses to do

Each of these is enforced by parsing the statement into an AST, not by pattern-matching the string. Regex checks for DROP are defeated by comments, casing and string literals; they are not used for the decision.

Attempt

Result

DELETE FROM invoices

Rejected — only SELECT is permitted

SELECT id FROM customers; DROP TABLE customers

Rejected — statement stacking

SELECT id FROM customers -- x\n; DELETE FROM invoices

Rejected — stacking hidden behind a comment

SELECT * FROM audit_log

Rejected — table not on the allowlist

SELECT name FROM sqlite_master

Rejected — schema introspection is via tools, not SQL

SELECT id FROM customers WHERE id IN (SELECT tool FROM audit_log)

Rejected — disallowed table in a subquery

SELECT load_extension('evil.so') FROM customers

Rejected — banned function

SELECT * FROM customers LIMIT 99999

Allowed, clamped to 500 rows

SELECT * FROM invoices

Rejected — unbounded scan of a large table

SELECT SUM(amount_cents) FROM invoices GROUP BY ...

Allowed — aggregates bound their own output

Every rejection carries a hint naming the specific table, column or clause that caused it, so the agent can correct itself rather than retrying blind:

Only SELECT is permitted; received "DELETE".

How to fix: This server is read-only. To change data, use issue_refund or
extend_trial, which require explicit confirmation.

What it masks

Email, phone and address columns come back partially redacted:

| company_name    | email                            |
| --------------- | -------------------------------- |
| Camden Digital  | ke***********@camdendigital.com  |
| Beacon Robotics | to************@beaconrobotics.com|

Masking happens on the way out, keyed on column name, which means it survives SELECT *, joins, and aliases. Filtering still works on the real value — searching priya finds her, the response just will not hand you her address book entry.

Set HARBOR_REVEAL_PII=true to turn it off.

How writes work

Writes are disabled unless the operator sets HARBOR_ALLOW_WRITES=true, and even then they cannot fire in one call.

Call 1 — no token. Nothing changes; you get a preview:

## Refund preview — nothing has changed yet

Invoice **inv_00002** for customer **cus_0001**
- Charged: $49.00
- Already refunded: $0.00
- **This refund: $10.00**
- After: $10.00 refunded of $49.00
- Reason: Service outage goodwill credit

To execute, call again with `confirm_token: "DJ7-O9d14gtk"`. Expires in 300s.

Call 2 — same arguments plus that token. Now it happens.

The preview is the point. It renders as plain text in the transcript, so a human reading along sees the exact amount and the exact invoice before anything is written. And because tokens live in process memory, a model that hallucinates a refund cannot execute one — it cannot invent a token that exists.

Tokens are single-use, expire in five minutes, and are bound to the exact arguments they were issued for. Replaying one with a larger amount_cents fails. A rejected attempt burns the token rather than letting an agent grind against it.

The audit log

Every call is recorded before the caller gets a response — allowed, denied or errored:

allowed  harbor_run_query      rows=  1  16ms  customers
denied   harbor_run_query      rows=  0   2ms  Only SELECT is permitted; received "DELETE".
allowed  harbor_issue_refund   rows=  0  66ms  preview
allowed  harbor_issue_refund   rows=  1  71ms  executed

The table is deliberately outside the allowlist. The agent writes to it by acting and cannot read, mine or edit it — so after a session you can answer "what did it actually do?" without trusting the agent's own account.


Tools

Tool

Purpose

harbor_list_tables

Readable tables, row counts, and a note on each

harbor_describe_table

Columns, types, nullability, which are masked

harbor_run_query

Guarded SELECT — the general-purpose escape hatch

harbor_find_customer

Turn "the Kestrel account" into a customer id

harbor_customer_360

Profile, subscription, billing, tickets, usage in one call

harbor_revenue_summary

Revenue by month, plan, country or industry

harbor_issue_refund

Refund an invoice — two-step

harbor_extend_trial

Extend a trial — two-step

One flexible query tool plus a few composite ones, rather than thirty narrow endpoints. An agent that can write SQL will out-compose any fixed set of endpoints; the guard is what makes that safe. The composite tools exist because some questions get asked constantly and deserve a single round trip.

harbor_revenue_summary also encodes a trap worth knowing about: trialing and canceled subscriptions carry mrr_cents = 0, so a naive AVG(mrr_cents) across all rows understates ARPA. The tool uses the right denominator so the agent does not have to know that.


Install

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": ["-y", "harbor-mcp-server"]
    }
  }
}

To allow refunds and trial extensions:

{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": ["-y", "harbor-mcp-server"],
      "env": { "HARBOR_ALLOW_WRITES": "true" }
    }
  }
}

Claude Code

claude mcp add harbor -- npx -y harbor-mcp-server

From source

git clone https://github.com/aayushsinghm16/harbor-mcp-server
cd harbor-mcp-server
npm install
npm run build
npm test
node dist/index.js

Configuration

Variable

Default

Effect

HARBOR_DB_PATH

./harbor.db

Database location. :memory: for a throwaway.

HARBOR_ALLOW_WRITES

false

Enables issue_refund and extend_trial.

HARBOR_REVEAL_PII

false

Returns email, phone and address unmasked.

Requires Node 22.5+. Hard limits live in src/constants.ts: 500 rows maximum, 50 by default, 25,000 characters per response, $500 maximum single refund, 30 days maximum trial extension.


Things to try

Point Claude at it and ask:

  • "Which customers churned, and what reasons did they give?"

  • "Show me revenue by month for the first half of 2026."

  • "Which plan carries the most MRR, and what's the average per account?"

  • "Tell me everything about the Kestrel account." — one customer_360 call

  • "Which accounts have both an open ticket and a failed payment?" — the churn-risk query

  • "Delete all the invoices." — watch it get refused, with a reason

The last one is the interesting one.


What this does not do

Being straight about the edges, because a security README that claims everything is a security README you should not trust.

Queries cannot be interrupted mid-flight. node:sqlite is synchronous and exposes no binding for sqlite3_interrupt, so the time budget is enforced by refusing expensive plans up front and by capping rows — not by killing a running query. Slow queries are logged, not stopped. If hard interruption is a requirement, execution needs to move to a worker thread that can be terminated. That is a deliberate trade, not an oversight.

Nothing is read from disk at runtime. The schema is a TypeScript module, not a .sql file, and there is no native addon. Both are the same lesson: a bundler tracing a serverless build follows import statements, not paths computed at runtime, so anything loaded by path is silently dropped and fails on the first request. Imports cannot go missing.

It needs Node 22.5 or newer. The database driver is node:sqlite, built into the runtime, so there is no native addon to compile and nothing for a bundler to lose while tracing a serverless build. The cost is a version floor and an ExperimentalWarning on stderr.

Masking is not anonymisation. Partial masks preserve enough structure to correlate rows. That is intentional — it is what makes the data still analytically useful — but it means the masking defends against casual exfiltration, not against a determined re-identification attack.

The allowlist is a table allowlist, not a row-level one. There is no per-tenant or per-user scoping. A real deployment against multi-tenant data needs row-level filtering injected into every query, which is a different and larger piece of work.

Confirmation tokens live in process memory. They do not survive a restart and are not shared across replicas. For a single stdio server that is correct; a horizontally scaled HTTP deployment would need shared storage.


Layout

src/
├── constants.ts          every safety boundary, in one file
├── db/
│   ├── schema.ts         six business tables plus the audit log, as a string
│   ├── connection.ts
│   └── seed.ts           deterministic — the same numbers on every machine
├── security/
│   ├── sql-guard.ts      AST parsing, allowlist, limit injection
│   ├── pii.ts            column-name-keyed masking
│   ├── confirm.ts        single-use, argument-bound tokens
│   └── audit.ts
├── services/
│   ├── query.ts          plan inspection and execution
│   └── format.ts         markdown/JSON rendering, truncation
└── tools/                one file per domain

51 tests cover the guard against statement stacking, comment-hidden injection, subquery smuggling, alias confusion, banned functions and limit evasion; the masking against SELECT * and joins; and the confirmation flow against replay, tampering and cross-tool reuse.

npm test

Licence

MIT.

Available Tools

8 tools
harbor_customer_360Full customer pictureA
Read-onlyIdempotent

Everything about one customer in a single call: profile, subscription, recent invoices, open tickets and 90-day usage totals.

Use this instead of four separate queries when a human asks about an account.

Args:

  • customer_id (string): exact id, format cus_0042

Returns JSON: { "customer": { id, company_name, contact_name, email, country, industry, employee_count, signed_up_at, churned_at, churn_reason, status }, "subscription": { plan, tier, status, seats, mrr_cents, started_at, trial_ends_at, canceled_at } | null, "billing": { invoices_total: number, paid_cents: number, refunded_cents: number, failed_count: number, recent: object[] }, "support": { open_count: number, resolved_count: number, avg_csat: number | null, recent: object[] }, "usage_90d": [ { feature: string, events: number, quantity: number } ] }

Example: "Why is Kestrel Robotics unhappy?" -> find_customer, then this tool; the open tickets and failed invoices usually answer it.

Error: returns an error naming the id if no such customer exists.

Inputs: customer_id (required).

harbor_describe_tableDescribe a Harbor tableA
Read-onlyIdempotent

Return the column list, types, nullability and primary key for one table.

Args:

  • table (string): one of customers, subscriptions, plans, invoices, tickets, usage_events

Returns JSON: { "table": string, "note": string, "columns": [ { "name": string, "type": string, "nullable": boolean, "primary_key": boolean, "masked": boolean } ] }

"masked" marks columns whose values are partially redacted on the way out.

Example: use before writing a query that filters on a column you have not seen yet. Error: returns an error listing valid tables if the name is not readable.

Inputs: table (required).

harbor_extend_trialExtend a trialA

Push a trialing subscription's end date out by a number of days. Requires two calls.

Call 1 — omit confirm_token to get a preview and a token. Call 2 — pass the token with identical arguments to apply it.

Args:

  • customer_id (string): format cus_0042

  • days (number): 1 to 30

  • reason (string): 4-200 chars

  • confirm_token (string, optional)

Returns for preview: { "stage": "preview", "confirm_token": string, "expires_in_seconds": number, "current_trial_ends_at": string, "new_trial_ends_at": string }

Returns for execute: { "stage": "executed", "customer_id": string, "new_trial_ends_at": string }

Refuses when the customer has no subscription, or the subscription is not in 'trialing' status — you cannot start a new trial for a paying or churned account.

Inputs: days (required), reason (required), customer_id (required), confirm_token.

harbor_find_customerFind a customerA
Read-onlyIdempotent

Search customers by company name, contact name, email or id.

Use this to turn a human's phrasing ("the Kestrel account") into a customer id before calling harbor_customer_360.

Args:

  • query (string): partial name, partial email, or exact id

  • limit (number): 1-50, default 10

Returns JSON: { "matches": [ { "id": string, "company_name": string, "contact_name": string, "email": string, "country": string, "status": "active" | "churned", "signed_up_at": string } ], "count": number }

Emails are partially masked. Matching still works on the unmasked value, so searching "priya" finds her even though the response shows "pr***@...".

Returns an empty match list, not an error, when nothing matches.

Inputs: query (required), limit.

harbor_issue_refundIssue a refundA
Destructive

Refund part or all of a paid invoice. Requires two calls.

Call 1 — omit confirm_token. Returns a preview of exactly what would change, plus a token valid for 5 minutes. Call 2 — pass that token with identical arguments. The refund is written.

Args:

  • invoice_id (string): exact id, format inv_00123

  • amount_cents (number): 1 to 50000

  • reason (string): 4-200 chars, stored in the audit log

  • confirm_token (string, optional): omit first, then supply

Returns for the preview call: { "stage": "preview", "confirm_token": string, "expires_in_seconds": number, "invoice": { id, customer_id, amount_cents, already_refunded_cents, status }, "would_refund_cents": number, "resulting_refunded_cents": number }

Returns for the execute call: { "stage": "executed", "invoice_id": string, "refunded_cents": number, "total_refunded_cents": number }

Refuses when: the invoice does not exist, is not paid, or the refund would exceed the amount actually charged.

Inputs: reason (required), invoice_id (required), amount_cents (required), confirm_token.

harbor_list_tablesList Harbor tablesA
Read-onlyIdempotent

List every table an agent may read, with row counts and a one-line note on each.

Call this first when you do not already know the schema. It is cheap and it prevents guessing.

Args: none.

Returns JSON: { "tables": [ { "name": string, "rows": number, "note": string } ], "pii_masked": boolean // true when email/phone/address columns come back partially redacted }

Tables not listed here cannot be queried — harbor_run_query will reject them.

Inputs: no named parameters.

harbor_revenue_summaryRevenue summaryA
Read-onlyIdempotent

Revenue broken down by month, plan, country or industry.

group_by='month' reads collected revenue from paid invoices, net of refunds. The other groupings read current MRR from live subscriptions, which is a different question — one is history, the other is run-rate.

Args:

  • group_by ('month' | 'plan' | 'country' | 'industry'): default 'month'

  • from (string, YYYY-MM-DD, optional): only for group_by='month'

  • to (string, YYYY-MM-DD, optional): only for group_by='month'

Returns JSON for group_by='month': { "basis": "collected_revenue", "rows": [ { "month": "2026-07", "invoices": number, "gross_cents": number, "refunded_cents": number, "net_cents": number } ], "totals": { "gross_cents": number, "refunded_cents": number, "net_cents": number } }

Returns JSON for the other groupings: { "basis": "current_mrr", "rows": [ { "": string, "customers": number, "mrr_cents": number, "arpa_cents": number } ], "totals": { "customers": number, "mrr_cents": number } }

Examples:

  • "How much did we collect in Q2?" -> group_by='month', from='2026-04-01', to='2026-06-30'

  • "Which plan carries most revenue?" -> group_by='plan'

  • "Where are our customers?" -> group_by='country'

Inputs: to, from, group_by.

harbor_run_queryRun a guarded SQL queryA
Read-onlyIdempotent

Run a read-only SQL query against the Harbor business database.

Every query is parsed and checked before execution. It will be rejected if it:

  • is not a SELECT (no INSERT, UPDATE, DELETE, DROP, ATTACH, PRAGMA)

  • contains more than one statement

  • touches a table outside: customers, subscriptions, plans, invoices, tickets, usage_events

  • calls a file or extension function

  • would scan the whole invoices or usage_events table without an index

A LIMIT is added if you omit one, and lowered if you exceed 500.

Args:

  • sql (string): one SQLite SELECT statement

  • limit (number, optional): row cap, 1-500, default 50

  • response_format ('markdown' | 'json'): default 'markdown'

Returns JSON: { "rows": object[], // result rows, PII columns partially masked "columns": string[], "row_count": number, "tables_read": string[], "limit_applied": number, "limit_adjusted": boolean, // true if we added or lowered your LIMIT "truncated": boolean, // true if the cap was hit and more data exists "masked_columns": string[], "duration_ms": number }

Examples:

  • "How many customers churned?" -> SELECT COUNT(*) FROM customers WHERE churned_at IS NOT NULL

  • "Revenue by plan" -> SELECT p.name, SUM(s.mrr_cents) FROM subscriptions s JOIN plans p ON p.id = s.plan_id GROUP BY p.name

  • Don't use for: changing data. Use harbor_issue_refund or harbor_extend_trial.

Errors are returned with a "How to fix" line. Read it — it names the specific column, table or clause that caused the rejection.

Inputs: sql (required), limit, response_format.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: schema discovery, query execution, customer lookup, customer snapshot, revenue reporting, and write actions. Even the two write tools are unambiguous—one targets invoices, the other targets subscriptions.

    Naming Consistency4/5

    All tools share the consistent 'harbor_' prefix and snake_case convention, with most following verb_noun naming (list_tables, describe_table, run_query, find_customer, issue_refund, extend_trial). 'customer_360' and 'revenue_summary' deviate slightly from the verb-first pattern but remain clear and readable.

    Tool Count5/5

    Eight tools is well within the ideal range and each earns its place. The set covers schema discovery, querying, customer-specific lookups, a 360 view, revenue reporting, and two common business actions without excess.

    Completeness4/5

    The tool surface covers the core read/query workflow plus the most needed write operations (refund and trial extension). Minor gaps exist—there are no direct ticket management or subscription modification tools—but the run_query tool can access underlying tables and the 360 view provides recent support/invoice context.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      SQL Server MCP server with AST-based query validation, read-only safety, schema exploration, ER diagram generation, and DBA toolkit integration (First Responder Kit, DarlingData, sp_WhoIsActive).
      12
      8
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Read-only MCP server for SQL databases (SQL Server, Postgres, SQLite) with multi-server support and three-layer safety using AST validation and linting.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server for SQL Server that exposes metadata and guarded SELECT queries with PII masking and five-layer guards.
      5
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for running read-only SQL queries across MySQL and PostgreSQL databases with safety guardrails, credentials stored outside source, and support for multiple databases.
      2
      MIT