Package Exports

@kopra-dev/mcp
@kopra-dev/mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@kopra-dev/mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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