KikoBooks MCP Server
A Model Context Protocol (MCP) server for KikoBooks — enterprise AI-agentic bookkeeping software. This server enables AI assistants like Claude, GitHub Copilot, and OpenAI-powered agents to interact with your KikoBooks accounting data through natural language.
Building an agent on top of this server? Read SKILL.md — the operating guide (status-first connect, write-tier approval, read-back verification, never expose secrets).
Maintaining or extending it? See CONTRIBUTING.md for the facts that must stay accurate and the release steps.
Features
- Chart of Accounts — Search, get, create, and update GL accounts
- Customers — Full CRUD with soft delete for customer management
- Invoices — Search, create, and manage AR invoices
- Items — Manage products and services
- Vendors — Full CRUD with soft delete for vendor management
- Bills — Full CRUD with void for AP bills
- Journal Entries — Search, create, post, and reverse GL journal entries
- Bill Payments — Search, create, and void AP payments
- Purchases / Expenses — Full CRUD with delete for expense transactions
- Customer Payments — Search, create, and manage AR payments
- Credit Memos — Search, create, and manage AR credit memos
- Sales Receipts — Search, create, and manage sales receipts
- CRM — Leads, deals, and pipeline (search/create/update), plus stage moves and customer promotion
- Proposals — Search and copy proposals; convert accepted proposals to invoices or jobs
- Workflow — Jobs (Projects/Engagements) and tasks; status updates and job-to-invoice billing
- Lifecycle bridges — CRM deal → proposal → job → invoice, end to end
- Reports — Trial balance, profit & loss, AR/AP aging, cash position, income/expense by category, business health (read-only)
- Banking — Bank accounts, imported transactions, and reconciliation sessions, plus the reconciliation lifecycle (start, set statement balance, complete, cancel)
- Deposits, Fixed Assets, Recurring Schedules, Statements — Search and get, plus deposit posting, fixed-asset depreciation and disposal, recurring-schedule controls, and statement sending
- Connection & discovery — Connection status and per-org enabled-module discovery (no secrets exposed)
CRM, Proposals, and Workflow tools require the org to have the Sales / Workflow modules enabled (always on for accounting firms; opt-in for self-service businesses). Call
get_enabled_modulesfirst to check.
Prerequisites
- Node.js 18 or higher
- A KikoBooks or Accountant.World organization (start free)
- An org API key: sign in, open Settings → API Keys (direct link), create a key, and copy it once. Keys can be scoped, set to expire, and revoked at any time.
Supported clients
Any MCP client that can launch a local (stdio) server: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code (GitHub Copilot), and others. ChatGPT connectors require a hosted (remote HTTPS) MCP endpoint, which KikoBooks does not offer yet.
Setup
Most users don't need this. To use the published server, skip to Configuration — the
npxcommand pulls it from npm automatically. The steps below are for local development / contributing.
- Install dependencies:
npm install
- Create a
.envfile (copy from.env.example):
KIKOBOOKS_BASE_URL=https://ai.kikobooks.com
KIKOBOOKS_API_KEY=your_api_key_here
- Build:
npm run build
Configuration
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"kikobooks": {
"command": "npx",
"args": ["-y", "@agentkiko/kikobooks-mcp-server@latest"],
"env": {
"KIKOBOOKS_BASE_URL": "https://ai.kikobooks.com",
"KIKOBOOKS_API_KEY": "your_api_key_here"
}
}
}
}
VS Code (GitHub Copilot)
Add to .vscode/mcp.json in your project:
{
"servers": {
"kikobooks": {
"command": "npx",
"args": ["-y", "@agentkiko/kikobooks-mcp-server@latest"],
"env": {
"KIKOBOOKS_BASE_URL": "https://ai.kikobooks.com",
"KIKOBOOKS_API_KEY": "your_api_key_here"
}
}
}
}
Claude Code
claude mcp add kikobooks \
-e KIKOBOOKS_BASE_URL=https://ai.kikobooks.com \
-e KIKOBOOKS_API_KEY=your_api_key_here \
-- npx -y @agentkiko/kikobooks-mcp-server@latest
Cursor / Windsurf
Add the same mcpServers block shown for Claude Desktop to ~/.cursor/mcp.json (Cursor) or
~/.codeium/windsurf/mcp_config.json (Windsurf).
Read-only mode
Write, update, and delete tools load by default. To give an assistant analysis-only access, add these
to the env block of any configuration above:
"KIKOBOOKS_DISABLE_WRITE": "true",
"KIKOBOOKS_DISABLE_UPDATE": "true",
"KIKOBOOKS_DISABLE_DELETE": "true"
Only get_*, search_*, and list_* tools are registered in this mode.
Local Development
For local development, point to the built output:
{
"servers": {
"kikobooks": {
"command": "node",
"args": ["/absolute/path/to/mcp-kiko/dist/index.js"],
"env": {
"KIKOBOOKS_BASE_URL": "https://ai.kikobooks.com",
"KIKOBOOKS_API_KEY": "your_api_key_here"
}
}
}
}
Available Tools (116 total)
Chart of Accounts
Customers
Invoices
Items (Products/Services)
Vendors
Bills (Accounts Payable)
Journal Entries
Bill Payments (Accounts Payable)
Purchases / Expenses
Customer Payments (AR)
Credit Memos (AR)
Sales Receipts
CRM (requires the Sales module)
Proposals (requires the Sales module)
Workflow (requires the Workflow module)
Connection & Discovery
Reports (read-only)
Banking & Reconciliation (read)
Deposits, Fixed Assets, Recurring, Statements (read)
Deposits / Fixed Assets / Recurring / Statements / Reconciliation (write)
Mutating — require a read-write API key and are hidden when KIKOBOOKS_DISABLE_WRITE is set.
Not yet exposed (deferred):
create_recurring_schedule,create_statement, and per-transaction bank match/categorize — their request bodies are large nested templates that warrant dedicated design rather than a best-effort mapping.
Scope tiers
Read tools (get_*, search_*, list_*) always load. Mutating tools load by default and are grouped
into scope tiers that can be suppressed at startup (set the flag to true or 1):
Security
- The API key is exchanged for short-lived JWTs. It is never written to disk, logged, or returned to the model.
- Every call goes through the same permission-checked KikoBooks API your team uses, scoped to the key's organization.
- Posted ledger entries cannot be edited or deleted through any tool; corrections are reversals or credit memos.
- MCP clients ask you to confirm tool calls before they run. Review each write before you approve it.
- Report vulnerabilities to [email protected] with the subject "Security vulnerability report".
Privacy and terms
- This package sends no telemetry. It runs on your machine and talks only to the
KIKOBOOKS_BASE_URLyou configure. - Nothing is written to disk unless you set
KIKOBOOKS_TOKEN_STORE_PATH; then only the short-lived session tokens are saved there (owner-only permissions on macOS and Linux), never the API key. - Your MCP client and the AI model it uses (for example, Claude or GitHub Copilot) see the tool results you request. Their providers' terms and privacy policies govern that data.
- Using KikoBooks through this server is covered by the KikoBooks Terms of Service and Privacy Policy. KikoBooks is offered to U.S. businesses only.
Authentication
The server supports two authentication methods:
API Key (Recommended)
Set KIKOBOOKS_API_KEY — the server automatically exchanges it for JWT tokens and handles refresh.
Direct Token
Set KIKOBOOKS_ACCESS_TOKEN (and optionally KIKOBOOKS_REFRESH_TOKEN) if you manage tokens externally.
Environment Variables
* Either KIKOBOOKS_API_KEY or KIKOBOOKS_ACCESS_TOKEN is required.
Development
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run watch
# Lint
npm run lint
Architecture
src/
├── index.ts # Entry point
├── config.ts # Env config (base URL, key, token-store path, scope flags)
├── clients/
│ ├── kikobooks-client.ts # HTTP client with JWT auth + auto-refresh (get/post/put/delete)
│ └── token-store.ts # Optional file-backed JWT cache (API key never persisted)
├── server/
│ └── kikobooks-mcp-server.ts # MCP server singleton
├── tools/ # Tool definitions grouped by verb, registered via tool-factory
│ ├── tool-factory.ts # Registers all tools + applies scope-tier gating
│ ├── search/ get/ create/ update/ delete/ action/
│ └── ... (116 tools)
├── handlers/ # Business logic (calls the API client)
├── helpers/ # register-tool, format-error, get-package-version
└── types/ # tool-definition, tool-response
Roadmap
See ROADMAP.md for the full implementation plan:
- Phase 1 ✅ Core Bookkeeping (12 accounting entities)
- Phase 2 ✅ Practice Management (CRM, Proposals, Workflow) + lifecycle bridges
- Phase 3 ✅ Banking & Reconciliation
- Phase 4 ✅ Reports & Analytics
License
MIT — see LICENSE
Links
- KikoBooks
- MCP Protocol Specification
- Accountant Inc. — publisher of KikoBooks, Accountant.World, and Agent Kiko