# @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.

[![English](https://img.shields.io/badge/lang-en-blue.svg)](README.md)
[![Persian](https://img.shields.io/badge/lang-fa-green.svg)](README.fa.md)

---

## Quick Start

```bash
# 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)

```bash
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_METHOD_OVERRIDE` | ❌ | `true` | Convert PUT/PATCH/DELETE to POST + `_method` override (required on hosts with ModSecurity that blocks raw methods with 406). Set to `false` to send PUT/PATCH/DELETE as-is |
| `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`)

```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`)

```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`)

```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](https://kamacrm.ir/docs)
- [GitHub Repository](https://github.com/AsemanServer/@kamacrm/mcp-server)
- [Kama CRM Website](https://kamacrm.ir)

## 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

```bash
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](LICENSE).