@kamacrm/mcp-server

MCP server for Kama CRM — Talk to your AI agent instead of clicking.

Connect Claude Code, OpenCode, Cline, or any MCP-compatible client directly to your Kama instance. The server auto-discovers all your API endpoints via the OpenAPI spec and exposes them as MCP tools.

Quick Start

# One command — no install needed
KAMA_URL=https://your-kama.com KAMA_API_TOKEN=xxx npx @kamacrm/mcp-server

Related MCP server: OpenAPI MCP Server

Installation

Via npm (recommended for repeated use)

npm install -g @kamacrm/mcp-server

kama-mcp
# Then configure KAMA_URL and KAMA_API_TOKEN in your environment

Via npx (zero install)

Add to your MCP client config — it auto-installs on first run.

Configuration

Getting an API Token

1. Log into your Kama instance as admin

2. Go to Settings → API Keys (or equivalent)

3. Create a new API key

4. Copy the token — it's your KAMA_API_TOKEN

💡 The token must belong to a user with sufficient permissions. The MCP server respects all Kama access controls — users can only do what they have permission to do.

Usage with AI Clients

Claude Code (.claude.json)

{
  "mcpServers": {
    "kama": {
      "command": "npx",
      "args": ["@kamacrm/mcp-server"],
      "env": {
        "KAMA_URL": "https://your-kama.com",
        "KAMA_API_TOKEN": "your-token-here"
      }
    }
  }
}

OpenCode (opencode.json)

{
  "mcpServers": {
    "kama": {
      "command": "npx",
      "args": ["@kamacrm/mcp-server"],
      "env": {
        "KAMA_URL": "https://your-kama.com",
        "KAMA_API_TOKEN": "your-token-here"
      }
    }
  }
}

Cline (cline_mcp_settings.json)

{
  "mcpServers": {
    "kama": {
      "command": "npx",
      "args": ["@kamacrm/mcp-server"],
      "env": {
        "KAMA_URL": "https://your-kama.com",
        "KAMA_API_TOKEN": "your-token-here"
      }
    }
  }
}

VS Code (via Continue or Cline extension)

Same config format in the extension's MCP settings file.

How It Works

Your AI Agent (Claude/OpenCode/Cline)
        │
        │  stdio (JSON-RPC 2.0)
        ▼
   @kamacrm/mcp-server
        │
        │  1. Fetches OpenAPI spec from GET /api/docs
        │  2. Auto-generates MCP tools for every endpoint
        │  3. Proxies tool calls as HTTP requests
        │
        ▼
   Kama REST API
        │
        ▼
   Kama Services / Database

1. On startup, the server fetches GET /api/docs from your Kama instance

2. It parses the OpenAPI 3.0.1 spec and creates one MCP tool per API endpoint

3. Your AI agent discovers all 200+ tools via tools/list

4. When the agent calls a tool, the server proxies the request to your Kama API

5. All requests use your API token — permissions are enforced by Kama

Tool Naming Convention

Tools are automatically named based on the method, tag, and path:

kama_{method}_{category}_{action}

Examples:
  kama_get_clients_list         → GET  /clients
  kama_post_clients_create      → POST /clients
  kama_get_clients_show         → GET  /clients/{id}
  kama_put_clients_update       → PUT  /clients/{id}
  kama_delete_clients_delete    → DEL  /clients/{id}
  kama_get_invoices_list        → GET  /invoices
  kama_post_tickets_store       → POST /tickets
  kama_get_settings_index       → GET  /settings

Features

• Agent context — built-in instructions (protocol 2025-06-18) teach the agent what Kama is, what you can do, and to confirm before any create/update/delete

• 111 curated tools — hand-crafted schemas with exact field types, required fields, enums and Persian descriptions for the most-used endpoints

• Zero configuration — auto-discovers your entire API from the OpenAPI spec (500+ tools)

• Always up-to-date — tools reflect your actual Kama API, no manual sync

• Permission-aware — respects Kama's access control, users can only do what they're allowed

• Confirmation hints — destructive tools are flagged (destructiveHint), clients show confirmation dialogs

• Prompts — kama-intro, kama-common-tasks, kama-report for quick starts

• Resource — kama://about with system info and module catalog

• Language-agnostic — works with any MCP client (Claude Code, OpenCode, Cline, Continue, etc.)

• Cross-platform — runs anywhere Node.js 18+ runs (Linux, macOS, Windows)

• Lightweight — zero npm dependencies, pure Node.js

Resources

• Full API Documentation

• GitHub Repository

• Kama CRM Website

Support

• Phone: 05144228000

• Email: via Kama website

FAQ

Q: Does this require a plugin installed on Kama? No. The MCP server is completely standalone. It only needs HTTP access to the Kama REST API.

Q: Are all endpoints exposed? Every route in /api/docs becomes an MCP tool. This includes public endpoints (login, docs) and authenticated endpoints.

Q: Is it safe? Yes. The MCP server uses your API token and respects all Kama permissions. Users can only perform actions they already have permission for. Write operations are clearly distinguished from read-only operations.

Q: Does it work with Cloud Kama instances? Yes. Set KAMA_URL to your cloud instance URL. The server connects over standard HTTPS.

Q: My API token expires, what then? Restart the MCP server with a fresh token. Most Kama API tokens are long-lived.

Q: Too many tools? The auto-discovery includes everything. You can configure your MCP client to only expose specific tools if needed.

Q: Why do updates/deletes fail with 406? Production hosts run ModSecurity (on LiteSpeed), which rejects raw PUT/PATCH/DELETE requests with 406 Not Acceptable before they reach Kama. The MCP server automatically converts these to POST with a _method override (plus X-HTTP-Method-Override), so updates and deletes work transparently. If your host supports raw methods, disable this with KAMA_METHOD_OVERRIDE=false.

Q: How do I attach images to products? It depends on the product type. Store products (the Website plugin's shop) are created/updated with kama_post_website_v1_products / kama_put_website_v1_products: pass an images array of media JSON strings (format {"type":"file_manager","file":{"file_name":"..."},"alt":""}) — the first image is the featured one. You can upload a file first with kama_post_uploader_files (base64 content + file name) and use the returned file_name inside the media JSON. The core kama_*_items_* tools are inventory items only — they do not manage store product product_type or images.

Development

git clone https://github.com/AsemanServer/kama-mcp-server.git
cd mcp-server

# Run directly
KAMA_URL=https://your-kama.com KAMA_API_TOKEN=xxx node bin/kama-mcp.js

# Test with a sample input
echo '{"jsonrpc":"2.0","id":1,"method":"list_tools"}' | KAMA_URL=... KAMA_API_TOKEN=... node bin/kama-mcp.js

License

MIT — see LICENSE.