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