Kadam Ad Network
Kadam advertising platform — manage ads, campaigns, creatives, audiences and stats
Open source Open in the app JSON README (API)
About
Kadam advertising platform — manage ads, campaigns, creatives, audiences and stats
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- kadam-official
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.4
- Last push
- 2026-09-07T09:56:25Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:00:18
- Updated
- 2026-08-29 04:00:18
- Origin id
io.github.kadam-official/mcp-server
README
# @kadam-net/mcp-server
[](https://www.npmjs.com/package/@kadam-net/mcp-server)
[](https://www.npmjs.com/package/@kadam-net/mcp-server)
[](https://github.com/kadam-official/mcp-server/blob/main/LICENSE)
[](https://nodejs.org)
[](https://registry.modelcontextprotocol.io)
MCP server for [Kadam](https://kadam.net) ad network — manage campaigns, creatives, audiences, sites, and analytics via AI agents.
Built on the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), the open standard for connecting LLMs to external tools and data.
## Install (one click)
### Cursor
<a href="https://kadam-official.github.io/mcp-server/install.html"><img alt="Install in Cursor" src="https://cursor.com/deeplink/mcp-install-dark.png" height="32" /></a>
Or add manually to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"kadam": {
"command": "npx",
"args": ["-y", "@kadam-net/mcp-server"],
"env": {
"KADAM_ADV_API_KEY": "your-advertiser-api-key",
"KADAM_PUB_API_KEY": "your-publisher-api-key"
}
}
}
}
```
### Claude Code
```bash
claude mcp add kadam -- npx -y @kadam-net/mcp-server
```
Then set the env var: `export KADAM_ADV_API_KEY=your-key`
### Claude Desktop
<a href="https://github.com/kadam-official/mcp-server/releases/latest/download/kadam-mcp-server.mcpb"><img alt="Download for Claude Desktop" src="https://img.shields.io/badge/Claude_Desktop-Download_.mcpb-orange?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0tMSAxNXYtNEg4bDQtNiA0IDZoLTN2NGgtMnoiLz48L3N2Zz4=" height="32" /></a>
Download → double-click → Install. Or add manually to `claude_desktop_config.json` (Settings → Developer → Edit Config):
```json
{
"mcpServers": {
"kadam": {
"command": "npx",
"args": ["-y", "@kadam-net/mcp-server"],
"env": {
"KADAM_ADV_API_KEY": "your-advertiser-api-key",
"KADAM_PUB_API_KEY": "your-publisher-api-key"
}
}
}
}
```
### Any MCP client (universal one-liner)
```bash
npx add-mcp @kadam-net/mcp-server
```
### Docker
```bash
docker run -i --rm \
-e KADAM_ADV_API_KEY=your-key \
kadam/mcp-server:latest
```
### npm global
```bash
npm install -g @kadam-net/mcp-server
KADAM_ADV_API_KEY=your-key kadam-mcp-server
```
## Configuration
| Variable | Required | Description |
| -------------------- | ---------- | ------------------------------------------------------------------------------------------ |
| `KADAM_ADV_API_KEY` | One of two | Advertiser API key from [partners.kadam.net](https://partners.kadam.net) -> Profile -> API |
| `KADAM_PUB_API_KEY` | One of two | Publisher API key from [pub.kadam.net](https://pub.kadam.net) -> Profile -> API |
| `KADAM_ADV_API_BASE` | No | Advertiser API URL (default: `https://partners.kadam.net/api/v1`) |
| `KADAM_PUB_API_BASE` | No | Publisher API URL (default: `https://pub.kadam.net/api`) |
| `LOG_LEVEL` | No | Log level: `trace`, `debug`, `info`, `warn`, `error`, `fatal` (default: `info`) |
At least one API key must be provided in stdio mode. In HTTP mode, tokens are passed per-request via Bearer authentication.
### HTTP Transport (multi-tenant deployment)
For server-side deployment serving multiple users:
| Variable | Required | Description |
| ------------------ | -------- | ----------------------------------------------------------------- |
| `MCP_TRANSPORT` | No | `"stdio"` (default) or `"http"` |
| `MCP_HTTP_PORT` | No | HTTP port (default: `8080`) |
| `MCP_HTTP_HOST` | No | Bind address (default: `0.0.0.0`) |
| `KADAM_ADV_DOMAIN` | No | Advertiser domain for PRM (default: `https://partners.kadam.net`) |
| `KADAM_PUB_DOMAIN` | No | Publisher domain for PRM (default: `https://pub.kadam.net`) |
```bash
docker run -d --name kadam-mcp \
-e MCP_TRANSPORT=http \
-p 8080:8080 \
kadam/mcp-server:latest
```
### Connecting via HTTP (Cursor / Claude)
```json
{
"mcpServers": {
"kadam-adv": {
"url": "https://partners.kadam.net/mcp",
"headers": {
"Authorization": "Bearer YOUR_ADV_API_KEY"
}
}
}
}
```
### Connecting via OAuth (ChatGPT)
Add `https://partners.kadam.net/mcp` (advertiser) or `https://pub.kadam.net/mcp` (publisher) as Server URL in ChatGPT settings. OAuth discovery, registration, and login happen automatically.
## Tools (31)
### Advertiser Tools (22)
Requires `KADAM_ADV_API_KEY`.
#### Campaigns
| Tool | Description | Annotations |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `kadam_adv_list_campaigns` | List campaigns with filters (folder, status, type, date, search) and pagination | readOnly |
| `kadam_adv_get_campaign` | Get full campaign configuration by ID: landing page URL, bids per country, budgets, targeting, frequency caps, schedule, conversion settings | readOnly |
| `kadam_adv_create_campaign` | Create campaign with full targeting (countries, devices, OS, browsers, age, gender, audiences) | — |
| `kadam_adv_update_campaign` | Update any campaign fields by ID | — |
| `kadam_adv_set_campaign_status` | Bulk status change (active/paused/archived) for comma-separated IDs | idempotent |
#### Bid Management
| Tool | Description | Annotations |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------- |
| `kadam_adv_update_campaign_bid` | Update bid for a single campaign (lightweight, no full payload). Falls back to current countries if omitted | idempotent |
| `kadam_adv_bulk_update_bids` | Update bids for multiple campaigns at once (all must share the same pricing model) | idempotent |
| `kadam_adv_update_site_bids` | Set per-site (zone) bids: static (`0.05`), multiplier (`x1.5`), or remove (`0`) | idempotent |
#### Campaign Folders
| Tool | Description | Annotations |
| ---------------------------------- | --------------------------------------------- | ----------- |
| `kadam_adv_list_campaign_folders` | List folders with campaign counts and budgets | readOnly |
| `kadam_adv_create_campaign_folder` | Create a new folder (name min 4 chars) | — |
| `kadam_adv_update_campaign_folder` | Update folder budgets and distribution | — |
#### Creatives
| Tool | Description | Annotations |
| ------------------------------- | -------------------------------------------------------- | ----------- |
| `kadam_adv_list_creatives` | List creatives by campaign, status, or search query | readOnly |
| `kadam_adv_create_creative` | Create creative for a campaign (goes through moderation) | — |
| `kadam_adv_update_creative` | Update creative fields | — |
| `kadam_adv_set_creative_status` | Bulk status change for creatives | idempotent |
#### Audiences
| Tool | Description | Annotations |
| --------------------------- | ------------------------------------------------------ | ----------- |
| `kadam_adv_list_audiences` | List audiences with search and sorting | readOnly |
| `kadam_adv_get_audience` | Get detailed audience info by ID | readOnly |
| `kadam_adv_create_audience` | Create audience (pixel, code, fingerprint, or S2S) | — |
| `kadam_adv_update_audience` | Update audience settings | — |
| `kadam_adv_delete_audience` | Delete audience permanently (requires `confirm: true`) | destructive |
#### Finance & Statistics
| Tool | Description | Annotations |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `kadam_adv_list_finance_operations` | Transaction history (deposits, charges, refunds) | readOnly |
| `kadam_adv_get_stats` | Unified statistics — 3 report types via `reportType` param: `custom` (report builder with dimension/metric mapping), `sites` (per-site breakdown), `postbacks` (conversion logs) | readOnly |
### Publisher Tools (9)
Requires `KADAM_PUB_API_KEY`.
#### Sites (Sources)
| Tool | Description | Annotations |
| ----------------------------- | ------------------------------------------------------ | ----------- |
| `kadam_pub_list_sources` | List publisher sites with stats | readOnly |
| `kadam_pub_create_source` | Add a new site (starts verification flow) | — |
| `kadam_pub_get_source` | Get detailed site info | readOnly |
| `kadam_pub_update_source` | Update site name | — |
| `kadam_pub_set_source_status` | Change site status (active/paused/archived/unarchived) | idempotent |
#### Ad Units
| Tool | Description | Annotations |
| ------------------------------ | ----------------------------------------------------------------------------------- | ----------- |
| `kadam_pub_list_ad_units` | List ad units for a site, filter by format (native/banner/push/popunder/inpagepush) | readOnly |
| `kadam_pub_set_ad_unit_status` | Change ad unit status (active/paused/archived/restored) | idempotent |
#### User & Statistics
| Tool | Description | Annotations |
| ------------------------- | ----------------------------------------------------------------- | ----------- |
| `kadam_pub_get_user_info` | Get publisher account info and balance | readOnly |
| `kadam_pub_get_stats` | Publisher statistics with human-readable dimension/metric mapping | readOnly |
## Resources (7)
Static reference data the agent can read before calling tools:
| URI | Description |
| ------------------------------------- | ------------------------------------------------------------------- |
| `kadam://reference/campaign-types` | All ad format types with IDs, features, pricing, and creative specs |
| `kadam://reference/pricing-models` | CPC, CPM, CPV, CPA Target with IDs and descriptions |
| `kadam://reference/creative-formats` | Creative requirements per campaign type |
| `kadam://reference/ad-unit-types` | Publisher ad unit formats with IDs |
| `kadam://reference/site-states` | Publisher site lifecycle states |
| `kadam://reference/report-dimensions` | Available dimensions and metrics for statistics tools |
| `kadam://reference/api-overview` | General Kadam API capabilities overview |
## Prompts (4)
Pre-built workflow templates that guide the agent through multi-step operations:
| Prompt | Description | Arguments |
| ---------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `kadam_launch_campaign` | Step-by-step campaign creation (check types -> create folder -> create campaign -> add creatives) | `type`, `name`, `url`, `budget` |
| `kadam_campaign_performance` | Campaign performance analysis with optimization recommendations | `campaignId`, `period` |
| `kadam_optimize_sites` | Analyze site performance and suggest blacklist/whitelist changes | `campaignId`, `minClicks`, `maxCPA` |
| `kadam_account_overview` | Full account overview — campaigns, spend, top performers | — |
## Architecture
```
src/
├── index.ts # Entry point, server instructions, transport
├── config.ts # Zod-validated env config with cache
├── errors.ts # AuthError class
├── logger.ts # Pino structured logging (stderr)
├── output-formatter.ts # Text formatting + 50KB truncation
├── middleware/
│ └── tool-wrapper.ts # Auth, error handling, logging middleware
├── api/
│ ├── http-client.ts # Generic HTTP client with retry/429/timeout
│ ├── partners-client.ts # Advertiser API (lazy singleton)
│ └── pub-client.ts # Publisher API (lazy singleton)
├── utils/
│ ├── pagination.ts # Shared pagination extraction
│ ├── cache-once.ts # Generic async cache-once utility
│ └── dimension-mapper.ts # Stats dimension name→ID resolution
├── types/
│ ├── common.ts # Shared types (ApiListResponse, ReportConfig)
│ ├── advertiser.ts # Campaign, Creative, Audience types + maps
│ ├── publisher.ts # Source, AdUnit, PubUser types + maps
│ └── tool-module.ts # ToolModule interface
├── tools/
│ ├── advertiser/ # 21 tools across 6 modules
│ └── publisher/ # 9 tools across 4 modules
├── resources/ # 7 static reference resources
└── prompts/ # 4 workflow prompts
```
### Key Design Decisions
- **ToolWrapper middleware** — centralized auth validation, error formatting, and logging for all 30 tools
- **Lazy singleton API clients** — one `HttpClient` instance per product, created on first use
- **Output truncation** — hard 50KB limit per response with `maxResults` (default 25, max 100) to prevent LLM context overflow
- **Human-readable output** — formatted tables, aligned entities, pagination metadata instead of raw JSON
- **Tool annotations** — `readOnlyHint`, `destructiveHint`, `idempotentHint` to guide agent behavior
- **Server instructions** — usage patterns and constraints sent to the LLM on connection
- **Dimension mapping** — stats tools accept human-readable names ("clicks", "spend") and resolve them to API IDs internally
## Development
### Prerequisites
- Node.js >= 18
- npm
### Setup
```bash
git clone https://github.com/kadam-official/mcp-server.git
cd mcp-server
npm install
cp .env.example .env # Fill in your API keys
```
### Commands
```bash
npm run dev # Watch mode with tsx
npm run build # Production build with Vite
npm run start # Run built server
npm run typecheck # TypeScript check
npm run lint # ESLint
npm run format # Prettier
npm test # Run 82 tests
npm run test:coverage # Tests with V8 coverage
npm run inspect # MCP Inspector (visual debugger)
```
### Testing
202 tests across 23 files using Vitest + MCP SDK InMemoryTransport:
- **Unit tests** — output formatter, config, HTTP client (mocked fetch)
- **Middleware tests** — ToolWrapper auth, error formatting, logging
- **Integration tests** — full server with all 30 tools, 7 resources, 4 prompts via in-memory MCP client
- **Tool handler tests** — each tool module with mocked API clients
```bash
npm test
# Test Files 23 passed (23)
# Tests 202 passed (202)
```
### MCP Inspector
The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) provides a visual interface for testing:
```bash
npm run build
npm run inspect
```
## Deployment
### Docker
```bash
docker build -t kadam-mcp-server .
docker run -i --rm -e KADAM_ADV_API_KEY=... kadam-mcp-server
```
### CI/CD
The `.gitlab-ci.yml` pipeline includes:
- **lint** — ESLint + TypeScript check
- **test** — Vitest with coverage
- **build** — Vite production build
- **publish** — npm publish + Docker push (manual trigger)
## License
MIT