Keitaro TDS API

You can run the Keitaro TDS API MCP Plugin as an MCP server to manage Keitaro campaigns, streams, offers, and related entities from your MCP client. This guide walks you through how to use the server, install it, and configure it securely so you can automate Keitaro tasks from your MCP environment.

How to use

Connect your MCP client to the Keitaro MCP server to start managing Keitaro entities. You can perform common actions like listing, retrieving, creating, updating, and deleting campaigns, streams, sources, offers, and related data. Use the client’s built‑in MCP commands to invoke the functions exposed by the server and fetch results directly into your workflow.

• Launch your MCP client and select the Keitaro server when prompted
• Use the exposed tools to list campaigns and offers, view details for specific items, or run reports
• Combine multiple tool calls to automate workflows such as reporting or batch updates
• Ensure your API configuration is loaded so the server can communicate with Keitaro APIs
• Monitor results and handle errors by inspecting returned data and logs

How to install

Prerequisites: you need a working Node.js environment and an MCP client installed in your setup. Ensure Node.js (LTS version) is installed before proceeding.

# Clone the MCP Keitaro TDS plugin repository
git clone <repository-url>
cd mcp-keitaro-tds

# Install dependencies
npm install

# Install the MCP package globally
npm install -g .

# Install the plugin in Cursor
node install-cursor-plugin.js

# Restart Cursor

Alternative: manual Cursor configuration (if you prefer editing the MCP settings directly). You will add a Keitaro MCP server entry to Cursor’s MCP configuration.

# Manual Cursor configuration
# On macOS
open ~/.cursor/mcp.json

# On Windows
notepad %USERPROFILE%\.cursor\mcp.json

# On Linux
nano ~/.cursor/mcp.json

If you choose the manual path, add this entry to the mcpServers section:

"Keitaro": {
  "command": "mcp-keitaro-tds",
  "args": []
}

API Key Configuration creates an environment file in the project root with the required values. Create a .env file containing these parameters so the server can authenticate with Keitaro TDS API.

KEITARO_API_URL=http://your-keitaro-domain.com/admin_api/v1
KEITARO_API_KEY=your-api-key

Configuration and usage notes

The server expects to be started by the MCP client or by the Cursor integration. Ensure the .env file is present in the project root and that KEITARO_API_URL and KEITARO_API_KEY contain your valid Keitaro API endpoint and key. The Keitaro MCP server will use these values to authenticate requests and perform actions against your Keitaro instance.

If you encounter connectivity or authentication issues, verify that your API URL is reachable from the host running the MCP server and that the API key has the necessary permissions for the requested operations.

Security tip: treat API credentials as secrets. Do not commit the .env file to version control. Use appropriate access controls on the host running Cursor and the MCP server.

Notes and troubleshooting

Common tasks you can perform with the server include managing campaigns, traffic streams, traffic sources, offers, and generating reports. If a particular operation returns an error, check the corresponding Keitaro API permissions and ensure the item IDs you use exist in your Keitaro instance.

Available tools

list_campaigns

Retrieve a list of campaigns available in Keitaro TDS API.

get_campaign

Fetch detailed information for a specific campaign by its ID.

create_campaign

Create a new campaign with specified properties.

update_campaign

Update fields of an existing campaign.

delete_campaign

Remove a campaign from Keitaro.

list_streams

List traffic streams related to campaigns.

get_stream

Get information about a specific traffic stream.

list_traffic_sources

List available traffic sources.

get_traffic_source

Get details for a specific traffic source.

list_offers

List offers present in Keitaro.

get_offer

Retrieve details for a specific offer.

list_clicks

List clicks recorded for campaigns/streams.

get_click

Retrieve information about a specific click.

list_conversions

List conversions tracked by Keitaro.

get_conversion

Get detailed data for a specific conversion.

get_report

Generate a report with the requested parameters.

list_domains

List domains configured in Keitaro.

get_domain

Get details for a specific domain.