KikoBooks MCP记账服务

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_modules first 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 npx command pulls it from npm automatically. The steps below are for local development / contributing.

1. Install dependencies:

npm install

2. Create a .env file (copy from .env.example):

KIKOBOOKS_BASE_URL=https://ai.kikobooks.com
KIKOBOOKS_API_KEY=your_api_key_here

3. 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 info@accountant.world 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_URL you 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