Integration Summary

# Connect KlickTipp with Claude or Codex via MCP

Use this guide to connect your local AI assistant such as Claude or Codex to your KlickTipp account through a local MCP server. This lets your agent inspect KlickTipp structures, work with KlickTipp Management API tools, and help you manage your contacts faster.

## Before You Start

Prepare the following before you start:

1. Access to a KlickTipp account with [username & password](/guides/management-api-authentication)
2. Installed local agent like Claude Code or local Codex clients


You do not need to manually check every technical requirement for the installation upfront. Your AI coding assistant should read the MCP server repository and check the current requirements for you.

## Step-by-step setup

Follow this simple recommended setup to use a KlickTipp Connection in your Coding Agent.

### Install the MCP server

Open a new chat in Claude or Codex to install the [binary KlickTipp MCP](https://github.com/klicktipp/klicktipp-mcp-binary).

Paste this prompt:

```text
Please set up the KlickTipp MCP server from the published release:
https://github.com/klicktipp/klicktipp-mcp-binary
```

Approve only the actions needed to read and clone the repository, create the local `.env` file, and run read-only tests. Do not approve publishing, committing, deleting files, or enabling write tools during setup.

If your agent supports local permission rules, add a deny rule for `.env` before filling in credentials so the agent cannot read or print that file later. Keep the rule narrow so `.env.example` stays readable.

### Connect to KlickTipp

After the Installation, check the settings and your connection to KlickTipp.

The `.env` file is your local settings file. The KlickTipp MCP server uses it to read your KlickTipp username and password. For safety, open this file yourself and enter your credentials manually outside the AI chat session.

1. Open the created `.env` file yourself in your local editor. Do not ask the AI assistant to open the file after credentials have been added.


```text
Show me the path to the generated .env file. Do not print the file contents.
```

1. Do not replace the whole file. Enter username & password directly into the local `.env` file. Do not paste KlickTipp credentials into the chat.


```dotenv
KT_AUTH_MODE=session
KT_USERNAME=your-klicktipp-username
KT_PASSWORD=your-klicktipp-password
```

1. Save your changes in the `.env` file.


Keep this file local. Do not commit `.env` to Git.

The repository already keeps `.env` out of Git and documents the same setup guardrails in `AGENTS.md`.

### Test The Connection

After the connection is configured, restart your AI assistant and open a new chat.

Test the connection via some example Prompts:

```text
List my KlickTipp tags.
```

```text
List my KlickTipp fields.
```

```text
List my KlickTipp opt-in processes.
```

If these read-only tests fail, fix the setup before enabling any write tools.

### Enable Write Tools

Enable the write tools only after read-only tools work. Write tools can change data in your KlickTipp account. Keep destructive tools disabled.

Update setting `KT_ENABLE_WRITES` in the `.env` file and save your changes:

```dotenv
KT_TOOL_MODE=full
KT_ENABLE_WRITES=true
KT_ENABLE_DESTRUCTIVE=false
```

Restart your AI coding assistant after changing `.env`.

## Troubleshooting

If the AI assistant cannot start the MCP server, ask it:

```text
Please inspect the MCP server logs, verify node -v and npm -v, check the .env file, and confirm that the MCP client points to the correct absolute path.
```

If authentication fails, check:

1. `KT_AUTH_MODE=session`
2. `KT_USERNAME`
3. `KT_PASSWORD`
4. Whether the account can log in normally
5. Whether the `.env` file is in the MCP server repository folder


## Advanced: Build Your Own MCP Server

The binary KlickTipp MCP server is the recommended setup for most users.

Build your own MCP server only if the KlickTipp API documentation has changed, the binary server does not support the API tools you need, or you want to experiment with a custom implementation.

Paste following Prompt in a new chat and start building:

```text
Build a local MCP server for KlickTipp from the current KlickTipp developer documentation.

Use these sources as the source of truth:
- https://developers.klicktipp.com/guides
- https://developers.klicktipp.com/management-api
- https://developers.klicktipp.com/guides/management-api-authentication
- https://developers.klicktipp.com/guides/management-api
```

## Advanced: Partner Authentication

For partner, production, or customer-facing multi-account integrations, do not use username/password setup. Use Developer Key plus Customer Key authentication instead: [Management API authentication](/guides/management-api-authentication).