@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

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

Variable	Required	Default	Description
KAMA_URL	✅	—	Your Kama instance URL (e.g. https://demo.kamacrm.ir)
KAMA_API_TOKEN	✅	—	Bearer token for API authentication
KAMA_DEBUG	❌	false	Enable debug logging to stderr (true/1)
KAMA_TIMEOUT	❌	30	Request timeout in seconds
KAMA_SERVER_NAME	❌	kama-mcp	Server name reported to MCP client

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

• Zero configuration — auto-discovers your entire API from the OpenAPI spec
• 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
• Read-only hints — GET endpoints are marked read-only for safe exploration
• 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.

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.