Ekwo OS — Claude Code MCP server: what it does, how to install
An MCP server connecting AI agents to Ekwo OS accounting on your Postgres or Supabase. It allows assistants to handle invoices, reconcile payments, and calculate VAT within user permissions.
claude mcp add --transport http mcp https://mcp.ekwo.ai/mcpWhat Ekwo OS — open source accounting: ledger, invoices and VAT on your own Supabase or Postgres does
The server gives coding agents direct access to double-entry books stored in Postgres or Supabase. Assistants can inspect ledgers, draft invoices, and organize tax filings without leaving the editor. Connections run through a remote HTTP endpoint at https://mcp.ekwo.ai/mcp or locally via stdio using npx -y @ekwo-ai/mcp@latest.
Permissions mirror the actual user rather than an elevated database administrator. The server deliberately rejects service_role keys on launch. Every request runs through Row Level Security policies, keeping multi-tenant organizations isolated. The agent cannot inspect locked accounting periods or foreign accounts.
The model cannot delete posted records. Any corrected transaction requires credit notes or explicit reversals handled by schema rules. Ledger rows are generated exclusively through database procedures. For direct Postgres connections without PostgREST, EKWO_ACT_AS_USER_ID is strictly required, and the environment needs the postgres npm package installed.
What it helps with
- generate and issue customer invoices directly through an AI agent
- match incoming bank payments against open transactions
- calculate VAT liabilities and assemble tax return drafts
- audit general ledger balances under row level security
Example prompts for the agent
- Review the ledger for last month and list all unmatched bank deposits.
- Draft a sales invoice for Acme Corp covering the recent consulting work.
- Prepare the preliminary VAT return using our posted transactions.
How to install Ekwo OS — open source accounting: ledger, invoices and VAT on your own Supabase or Postgres
1Platform CLI: remote server
claude mcp add --transport http mcp https://mcp.ekwo.ai/mcp2Platform CLI
claude mcp add --env SUPABASE_URL=<SUPABASE_URL> --env SUPABASE_ANON_KEY=<SUPABASE_ANON_KEY> --env EKWO_EMAIL=<EKWO_EMAIL> --env EKWO_PASSWORD=<EKWO_PASSWORD> --env EKWO_ACCESS_TOKEN=<EKWO_ACCESS_TOKEN> --transport stdio mcp -- npx -y @ekwo-ai/mcpReplace <…> with your own values. 3 more environment variables are in the server README
1Platform CLI: remote server
codex mcp add mcp --url https://mcp.ekwo.ai/mcp2Platform CLI
codex mcp add mcp --env SUPABASE_URL=<SUPABASE_URL> --env SUPABASE_ANON_KEY=<SUPABASE_ANON_KEY> --env EKWO_EMAIL=<EKWO_EMAIL> --env EKWO_PASSWORD=<EKWO_PASSWORD> --env EKWO_ACCESS_TOKEN=<EKWO_ACCESS_TOKEN> -- npx -y @ekwo-ai/mcpReplace <…> with your own values. 3 more environment variables are in the server README
Config file
{
"mcpServers": {
"mcp": {
"url": "https://mcp.ekwo.ai/mcp"
}
}
}{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@ekwo-ai/mcp"
],
"env": {
"SUPABASE_URL": "<SUPABASE_URL>",
"SUPABASE_ANON_KEY": "<SUPABASE_ANON_KEY>",
"EKWO_EMAIL": "<EKWO_EMAIL>",
"EKWO_PASSWORD": "<EKWO_PASSWORD>",
"EKWO_ACCESS_TOKEN": "<EKWO_ACCESS_TOKEN>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README
Config file
{
"servers": {
"mcp": {
"type": "http",
"url": "https://mcp.ekwo.ai/mcp"
}
}
}{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@ekwo-ai/mcp"
],
"env": {
"SUPABASE_URL": "<SUPABASE_URL>",
"SUPABASE_ANON_KEY": "<SUPABASE_ANON_KEY>",
"EKWO_EMAIL": "<EKWO_EMAIL>",
"EKWO_PASSWORD": "<EKWO_PASSWORD>",
"EKWO_ACCESS_TOKEN": "<EKWO_ACCESS_TOKEN>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README
1Platform CLI: remote server
gemini mcp add -t http mcp https://mcp.ekwo.ai/mcp2Platform CLI
gemini mcp add -e SUPABASE_URL=<SUPABASE_URL> -e SUPABASE_ANON_KEY=<SUPABASE_ANON_KEY> -e EKWO_EMAIL=<EKWO_EMAIL> -e EKWO_PASSWORD=<EKWO_PASSWORD> -e EKWO_ACCESS_TOKEN=<EKWO_ACCESS_TOKEN> mcp npx -y @ekwo-ai/mcpReplace <…> with your own values. 3 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Ekwo OS — open source accounting: ledger, invoices and VAT on your own Supabase or Postgres
How to install the Ekwo OS MCP server in Claude Code?
Run claude mcp add --transport http mcp https://mcp.ekwo.ai/mcp in your terminal. This registers the remote endpoint and starts browser-based authorization without storing database secrets in local configuration files.
What does the Ekwo OS MCP server do?
It lets an AI assistant maintain accounting books stored in your own Postgres or Supabase instance. The agent drafts invoices, matches payments, and inspects ledgers strictly within your assigned database permissions.
Why does the server refuse a Supabase service_role key?
A service_role key bypasses PostgreSQL row level security, exposing data across unrelated organizations. The server refuses to boot with this key and accepts only anonymous publishable keys tied to authenticated user credentials.
