@kopra-dev/mcp

MCP server that lets AI agents manage Kopra custom fields, tenant fields, and field values.

What it does

Model Context Protocol (MCP) allows AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients to interact with external tools. This server exposes 16 tools that map to the Kopra REST API, so an AI agent can create field groups, define fields, read and write field values, and configure webhooks - all through natural language.

Setup

Claude Code

claude mcp add kopra -- npx -y @kopra-dev/mcp

No configuration needed. The API key and base URL are passed as parameters on each tool call.

To pre-configure credentials (skips per-call auth prompts):

claude mcp add -e KOPRA_API_KEY=your-api-key kopra -- npx -y @kopra-dev/mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "kopra": {
      "command": "npx",
      "args": ["-y", "@kopra-dev/mcp"],
      "env": {
        "KOPRA_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop

Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "kopra": {
      "command": "npx",
      "args": ["-y", "@kopra-dev/mcp"],
      "env": {
        "KOPRA_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

Field Groups

| Tool | Description | |------|-------------| | list_field_groups | List all field groups | | get_field_group | Get a field group by ID with its global fields | | create_field_group | Create a new field group with a name and key | | update_field_group | Update a field group's name, description, or key | | delete_field_group | Soft-delete a field group |

Global Fields

| Tool | Description | |------|-------------| | list_global_fields | List all global fields | | create_global_field | Create a global field and assign it to field groups | | delete_global_field | Soft-delete a global field |

Tenant Fields

| Tool | Description | |------|-------------| | list_tenant_fields | List global and tenant-specific fields for a tenant | | create_tenant_field | Create a custom field for a specific tenant | | delete_tenant_field | Delete a tenant-specific field and its values |

Field Values

| Tool | Description | |------|-------------| | get_field_values | Get all field values for a specific entity | | save_field_values | Save field values as key-value pairs for an entity | | search_field_values | Search across field values with filters |

Webhooks

| Tool | Description | |------|-------------| | list_webhooks | List all webhook endpoints | | create_webhook | Create a webhook endpoint for field change notifications |

Authentication

Every tool accepts optional apiKey and baseUrl parameters. If KOPRA_API_KEY is set as an environment variable, it is used automatically and you don't need to pass it per-call.

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | KOPRA_API_KEY | No | - | Your Kopra API key (or pass apiKey per tool call) | | KOPRA_BASE_URL | No | https://api.kopra.dev | Kopra API base URL |

Development

npm install
npm run dev          # Run with tsx (uses stdio transport)
npm run build        # Compile TypeScript to dist/
npm run typecheck    # Type-check without emitting