@accos/mcp-server

ACCOS MCP server — Thai accounting OCR via Model Context Protocol.

Connects Claude Desktop, Cursor, Claude Code, n8n, or any MCP-compatible AI agent to ACCOS so the agent can read Thai receipts, tax invoices, and withholding tax certificates without you writing glue code.

Quick start

1. Get an API key + secret

Generate a key pair at accos.app/settings/api-keys. Both the key (ak_live_…) and the secret (sk_live_…) are required — every tool call is HMAC-signed.

2. Add to your MCP client

Claude Desktop — edit claude_desktop_config.json:

{
  "mcpServers": {
    "accos": {
      "command": "npx",
      "args": ["-y", "@accos/mcp-server"],
      "env": {
        "ACCOS_API_KEY": "ak_live_xxx",
        "ACCOS_API_SECRET": "sk_live_xxx"
      }
    }
  }
}

Cursor — edit ~/.cursor/mcp.json (same shape).

Claude Code — claude mcp add accos -- npx -y @accos/mcp-server, then set the two env vars in your shell.

Restart your agent — ACCOS tools appear in the tool list.

Tools

Tool	Cost	Purpose
inspect_file	free	Pre-flight: page count, MIME, advice
read_document	1 token	Extract data from a single-page receipt/invoice
verify_tax_id	1 token	Validate a 13-digit Thai tax ID against the RD/DBD registry
lookup_master	1 token	Search master data (vendors/customers/products)
list_my_templates	free	List custom templates accessible to this key
estimate_cost	free	Dry-run the cost of a planned tool call
get_balance	free	Current token balance + active batches
list_tasks	free	List open Task Tracker tasks you can see
my_tasks	free	Open tasks assigned to you
get_task	free	One task in full (checklist, comments, activity)
set_task_status	free	Move a task to todo / in_progress / review

Task Tracker tools

list_tasks, my_tasks, and get_task read the ACCOS Task Tracker module. They require:

• the API key scope tasks:read (tick "Grant read access to the Task Tracker module" when creating the key), and
• the Task Tracker module enabled on the account.

set_task_status additionally requires the scope tasks:write and editor access to the task's project. It can only move a task between todo, in_progress, and review — closing or cancelling a task stays a human action in the web app.

Visibility follows project membership — you only ever see tasks in projects you own, are a member of, or that are public. This is enforced server-side, not by company. Tasks are referenced as KEY-N (e.g. ACCOS-12); pass that ref to get_task for full detail.

Strict 1-page contract

read_document accepts EXACTLY ONE page per call. Multi-page PDFs are rejected — split them locally first:

# pypdf example
from pypdf import PdfReader, PdfWriter
for i, page in enumerate(PdfReader("input.pdf").pages):
    w = PdfWriter()
    w.add_page(page)
    w.write(f"page_{i}.pdf")

// pdf-lib example
import { PDFDocument } from "pdf-lib";
const src = await PDFDocument.load(await fs.readFile("input.pdf"));
for (let i = 0; i < src.getPageCount(); i++) {
  const out = await PDFDocument.create();
  const [pg] = await out.copyPages(src, [i]);
  out.addPage(pg);
  await fs.writeFile(`page_${i}.pdf`, await out.save());
}

Then call read_document once per page (parallel is fine, max 10 concurrent).

Destination is mandatory

Every read_document call MUST declare where the data is going:

• ar — sales invoices your company issued
• ap — purchase invoices your company received
• wht — withholding tax certificates (50 ทวิ)
• custom — anything else; also pass template_share_code

ACCOS never infers this from content. Ask the user if unclear.

Configuration reference

env var	required	default
ACCOS_API_KEY	yes	—
ACCOS_API_SECRET	yes	—
ACCOS_BASE_URL	no	https://accos.app (must be https:// unless localhost)
ACCOS_TIMEOUT_MS	no	60000

License

Apache-2.0