Skip to main content
Glama
nicofains1

Agentic Ads

by nicofains1

Agentic Ads

AI 代理的 Google AdSense。 只需在你的 MCP 服务器中添加 3 行代码。每次广告点击你获得 70% 收益。

npm version Tests License: MIT MCP Node

在线演示 · 快速开始 · MCP 工具 · 自托管


快速开始

步骤 1 — 注册并获取 API 密钥(30 秒):

访问网页表单:https://agentic-ads-production.up.railway.app/dev/register

或直接使用 API:

curl -X POST https://agentic-ads-production.up.railway.app/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My MCP Bot", "email": "me@example.com", "project_description": "A coding assistant that recommends dev tools"}'
# Returns: { "api_key": "aa_dev_...", "mcp_url": "https://agentic-ads-production.up.railway.app/mcp" }

步骤 2 — 添加到你的 MCP 客户端配置:

{
  "mcpServers": {
    "agentic-ads": {
      "url": "https://agentic-ads-production.up.railway.app/mcp",
      "transport": "http"
    }
  }
}

步骤 3 — 在你的代理中调用 search_ads 并通过每次点击获得收益:

// In your agent logic — when context is relevant
const ads = await mcp.callTool({
  name: 'search_ads',
  arguments: { query: 'best running shoes for marathon', max_results: 1 }
});

// Report events to get paid
await mcp.callTool({
  name: 'report_event',
  arguments: { ad_id: ads[0].ad_id, event_type: 'impression' }
});
// User clicks → report 'click' → you earn $0.35 on a $0.50 CPC ad

就这样。你已经开始盈利了。


Related MCP server: superhighway-mcp

为什么存在

你构建了一个出色的 MCP 服务器。用户很喜欢。但你却没有赚到钱。

agentic-ads 是 MCP 生态系统中缺失的盈利层。它就像 Google AdSense,但面向的是 AI 代理而不是网站。

问题

  • 存在 16,000+ 个 MCP 服务器。几乎没有哪个能盈利。

  • 开发者花费数周构建有用的工具,却赚不到一分钱。

  • 用户向代理询问产品推荐 → 代理抓取网页 → 品牌无法触达他们。

解决方案

通过 MCP 工具提供尊重隐私的上下文相关广告。开发者获得 70% 收入分成(行业领先)。广告主能够触达 AI 代理用户。各方共赢。


收入计算器

示例: 你的 MCP 服务器每月有 10,000 次查询,其中适合展示广告。

场景

每月展示次数

点击率

每月点击次数

每次点击成本

你的收入

保守

10,000

2%

200

$0.50

$70/月

现实

10,000

5%

500

$0.50

$175/月

强劲

10,000

8%

800

$0.75

$420/月

每月 100,000 次查询,点击率 5%: 每月被动收入 $1,750。

这意味着,只需在你的 MCP 服务器中添加 3 行代码,就能获得 每年 $21,000 的收入。


详细集成指南

面向 MCP 开发者(赚钱)

连接实时服务器并开始调用工具——无需审批流程,无最低要求。

// 1. When user asks about products/services
const ads = await mcp.callTool({
  name: 'search_ads',
  arguments: {
    query: 'best running shoes for marathon',
    max_results: 2
  }
});

// 2. Show relevant ad in your response (if it adds value)
// 3. Report impression
await mcp.callTool({
  name: 'report_event',
  arguments: { ad_id: 'ad_xyz', event_type: 'impression' }
});

// 4. If user clicks → report 'click' event
// You earn $0.35 on a $0.50 CPC click (70% revenue share)

面向广告主(触达 AI 用户)

# Create campaign + ad via MCP tools
mcp.callTool({
  name: 'create_campaign',
  arguments: {
    name: 'Q1 Running Shoes',
    total_budget: 500,
    pricing_model: 'cpc',
    bid_amount: 0.50
  }
});

mcp.callTool({
  name: 'create_ad',
  arguments: {
    campaign_id: 1,
    creative_text: 'Ultraboost 24 — 30% off! Free shipping.',
    link_url: 'https://adidas.com/ultraboost',
    keywords: ['running shoes', 'sneakers', 'marathon'],
    category: 'footwear'
  }
});

# Monitor analytics
mcp.callTool({ name: 'get_campaign_analytics', arguments: { campaign_id: 1 } });

工作原理

┌─────────────┐                    ┌──────────────────┐                    ┌──────────────┐
│  Advertiser  │────────────────────│  Agentic Ads MCP │────────────────────│  Your MCP     │
│  (Brand/API) │  create_campaign   │     Server       │  search_ads        │  Server       │
│              │  create_ad         │                  │  report_event      │               │
│              │  get_analytics     │  - Matching      │  get_guidelines    │  Shows ads    │
└─────────────┘                    │  - Billing       │                    │  to users     │
                                   │  - Auth & Rate   │                    └──────────────┘
                                   │  - Analytics     │
                                   └──────────────────┘

示例流程:

  1. 用户向你的代理提问:“最适合马拉松的跑鞋”

  2. 你的代理调用 search_ads → 获取按出价 × 相关性排序的相关广告

  3. 代理自然展示广告:“Ultraboost 24 — $126(30% 折扣)在 Adidas.com(赞助)”

  4. 用户点击 → 你报告 click 事件 → 你获得 $0.35(CPC 为 $0.50 时的 70%)

隐私: 不追踪用户,不建立用户画像,不使用 Cookie。仅进行上下文关键词匹配。


为什么 MCP 开发者喜欢这个

1. 行业领先的收入分成

70% 归你,30% 归平台。对比:

平台

开发者分成

agentic-ads

70%

Google AdSense

68%

Amazon Associates

1-10%

联盟网络

5-30%

2. 零摩擦设置

  • 无需合同,无最低要求,无审批延迟

  • 通过 POST /api/register 几秒内注册 → 获取 API 密钥

  • 将 1 个 MCP 服务器添加到配置 → 5 分钟内开始盈利

3. 尊重隐私

  • 不追踪用户,不建立用户画像

  • 不使用 Cookie,不进行浏览器指纹识别

  • 仅进行上下文关键词匹配(类似早期的 Google AdWords)

  • 你的用户隐私保持不变

4. 你控制展示哪些广告

  • 代理决定展示哪些广告(如果有)

  • 完整的用户上下文保留在本地(从不发送到广告服务器)

  • 相关性阈值由你掌控

  • 用户可以选择退出(“请不要展示广告”)

5. 透明的分析

  • 实时收入追踪

  • 精确查看你赚了多少钱、何时赚的、为什么赚的

  • 没有黑盒算法或隐藏费用


MCP 工具(共 8 个)

面向开发者(消费者端)——3 个工具

工具

认证

描述

search_ads

公开

通过查询/关键词/类别/地理位置搜索广告。返回带有相关性分数的排序结果。

report_event

开发者密钥

报告展示/点击/转化事件。触发收入计算。

get_ad_guidelines

公开

获取关于如何自然地向用户展示广告的格式指南。

面向广告主(发布者端)——5 个工具

工具

认证

描述

create_campaign

广告主密钥

创建广告活动,设置预算、目标、定价模式(CPC/CPM/CPA)。

create_ad

广告主密钥

创建广告,包含创意文案、关键词、定向、链接 URL。

get_campaign_analytics

广告主密钥

获取效果指标(展示次数、点击次数、转化次数、花费、ROI)。

update_campaign

广告主密钥

更新广告活动(暂停/恢复、调整预算、更改定向)。

list_campaigns

广告主密钥

列出所有广告活动及其摘要统计信息,可选状态筛选。


定价模式

选择你希望如何支付(广告主)或如何赚钱(开发者):

模式

广告主支付

开发者获得(70%)

收费时机

CPC(点击)

每次点击 $0.50

$0.35

用户点击广告链接

CPM(展示)

每 1000 次展示 $5.00

$3.50

广告展示给用户

CPA(转化)

每次转化 $10.00

$7.00

用户完成操作(购买、注册等)

预算控制: 设置总预算 + 每日上限。预算耗尽时自动暂停。


获取你的 API 密钥

要调用 report_event 或广告主工具,你需要一个 API 密钥。

选项 A — 网页表单(最简单):

访问 https://agentic-ads-production.up.railway.app/dev/register 并填写你的详细信息。你的 API 密钥会立即显示。

选项 B — API:

curl -X POST https://agentic-ads-production.up.railway.app/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My MCP Bot", "email": "me@example.com", "project_description": "A coding assistant"}'

响应:

{
  "developer_id": "...",
  "api_key": "aa_dev_...",
  "mcp_url": "https://agentic-ads-production.up.railway.app/mcp"
}

字段

必填

描述

name

是

你的项目或机器人名称

email

是

联系邮箱

project_description

否

你的 MCP 服务器的简要描述(最多 500 字符)

在 Authorization 头中使用 api_key:Authorization: Bearer aa_dev_...

在 Railway 上部署,使用持久化存储: 运行在 agentic-ads-production.up.railway.app 的实时服务器使用 Railway 的持久化卷——数据在部署和重启后保持不变。要自托管,请使用指向挂载卷的 DATABASE_PATH=/data/ads.db。


安装

选项 1:连接到实时服务器(最简单)

添加到你的 MCP 客户端配置(Claude Desktop、Cursor、Windsurf 等):

{
  "mcpServers": {
    "agentic-ads": {
      "url": "https://agentic-ads-production.up.railway.app/mcp",
      "transport": "http"
    }
  }
}

健康检查: https://agentic-ads-production.up.railway.app/health

选项 2:本地 stdio(开发)

npm install -g agentic-ads

# Add to MCP config
{
  "mcpServers": {
    "agentic-ads": {
      "command": "npx",
      "args": ["agentic-ads", "--stdio"]
    }
  }
}

选项 3:自托管(生产)

git clone https://github.com/nicofains1/agentic-ads.git
cd agentic-ads
npm install && npm run build

# Start HTTP server
PORT=19877 npm run start:http

# Or stdio
npm run start:stdio

标志:

node dist/server.js --http --port 19877 --db ./ads.db

标志

默认值

描述

--http

—

启动 HTTP 服务器(默认是 stdio)

--port N

3000

HTTP 端口

--db PATH

agentic-ads.db

SQLite 数据库路径

--api-key KEY

—

预认证 stdio 会话

环境变量:

PORT=19877                     # HTTP server port (alternative to --port)
DATABASE_PATH=/data/ads.db     # SQLite database path (default: agentic-ads.db)
AGENTIC_ADS_API_KEY=aa_dev_... # Developer API key for stdio mode

数据库持久化: 将 DATABASE_PATH 设置为持久化卷上的路径。首次使用空数据库运行时,会自动填充演示广告活动。有关完整部署指南,请参阅 DEPLOY.md(推荐使用 Railway 的免费持久化存储)。


集成示例

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agentic-ads": {
      "command": "npx",
      "args": ["agentic-ads", "--stdio"]
    }
  }
}

Cursor / Windsurf

{
  "mcpServers": {
    "agentic-ads": {
      "url": "https://agentic-ads-production.up.railway.app/mcp",
      "transport": "http"
    }
  }
}

自定义 TypeScript 代理

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['agentic-ads', '--stdio']
});

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

// Search for ads
const result = await client.callTool({
  name: 'search_ads',
  arguments: {
    query: 'best laptops for coding',
    keywords: ['laptop', 'programming'],
    category: 'electronics',
    max_results: 3
  }
});

console.log(result.content[0].text);
// Returns: { "ads": [ { "ad_id": "...", "creative_text": "...", "relevance_score": 0.87 } ] }

Streamable HTTP 会话管理

通过 HTTP 调用实时服务器时,必须手动管理 MCP 会话。以下是使用原始 fetch 的完整示例:

const BASE = "https://agentic-ads-production.up.railway.app";
const API_KEY = "aa_dev_..."; // from /api/register

const headers = {
  "Content-Type": "application/json",
  "Accept": "application/json, text/event-stream",
  "Authorization": `Bearer ${API_KEY}`,
};

// 1. Initialize — get a session ID
const initRes = await fetch(`${BASE}/mcp`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    jsonrpc: "2.0", id: 1, method: "initialize",
    params: {
      protocolVersion: "2024-11-05",
      capabilities: {},
      clientInfo: { name: "my-agent", version: "1.0.0" },
    },
  }),
});
const sessionId = initRes.headers.get("mcp-session-id");

// 2. Send initialized notification (required by MCP spec)
await fetch(`${BASE}/mcp`, {
  method: "POST",
  headers: { ...headers, "mcp-session-id": sessionId },
  body: JSON.stringify({
    jsonrpc: "2.0", method: "notifications/initialized", params: {},
  }),
});

// 3. Call tools — pass session ID on every request
const res = await fetch(`${BASE}/mcp`, {
  method: "POST",
  headers: { ...headers, "mcp-session-id": sessionId },
  body: JSON.stringify({
    jsonrpc: "2.0", id: 2, method: "tools/call",
    params: { name: "search_ads", arguments: { query: "running shoes", max_results: 2 } },
  }),
});

// 4. Parse response (SSE format: "event: message\ndata: {...}")
const text = await res.text();
const dataLine = text.split("\n").find((l) => l.startsWith("data:"));
const result = JSON.parse(dataLine.slice(5));
console.log(result.result.content[0].text);

关键点:

  • mcp-session-id 头在 initialize 时返回,必须在所有后续请求中发送

  • 认证(Authorization: Bearer ...)按会话设置——该会话中的所有工具调用都会继承它

  • 服务器使用 SSE(服务器发送事件)格式——从响应中解析 data: 行

  • 有关完整工作示例,请参阅 examples/demo-mcp-server


架构

┌─────────────────────────────────────────────────────────────┐
│  MCP Server (Node.js 22 + TypeScript)                       │
│  ┌───────────────┐  ┌──────────────┐  ┌─────────────────┐  │
│  │ Tool Registry │  │ Auth & Rate  │  │ Matching Engine │  │
│  │ (8 tools)     │  │ Limiting     │  │ (relevance²     │  │
│  │               │  │ (SHA-256)    │  │ × bid × quality)│  │
│  └───────────────┘  └──────────────┘  └─────────────────┘  │
│  ┌───────────────┐  ┌──────────────┐  ┌─────────────────┐  │
│  │ SQLite (WAL)  │  │ Revenue      │  │ Analytics       │  │
│  │ - Campaigns   │  │ Split Engine │  │ (real-time)     │  │
│  │ - Ads         │  │ (70/30)      │  │                 │  │
│  │ - Events      │  │              │  │                 │  │
│  └───────────────┘  └──────────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────────────┘
          │                                          │
          │                                          │
  Streamable HTTP (remote)                     stdio (local)

关键特性:

  • 隐私: 不追踪用户,仅进行上下文匹配

  • 相关性: score = relevance² × bidFactor × quality_score(相关性占主导)

  • 原子性: 事件插入 + 统计更新 + 收入分配在单个 SQLite 事务中完成

  • 速率限制: 每个密钥滑动窗口(根据工具不同,60-120 请求/分钟)

  • 认证: SHA-256 哈希 API 密钥,基于角色的访问控制

  • 测试: 270 个测试,分布在 13 个文件中,全部通过


演示:完整流程

# Clone repo
git clone https://github.com/nicofains1/agentic-ads.git
cd agentic-ads

# Install + build
npm install && npm run build

# Seed a local DB with demo data (generates real API keys)
tsx scripts/seed.ts --db test.db
# Note: seed.ts prints the generated dev/adv keys — use them below

# Run smoke test with real keys from seed output
tsx scripts/smoke-test.ts --db test.db --dev-key aa_dev_... --adv-key aa_adv_...

输出:

✅ Created advertiser: Adidas
✅ Created campaign: Q1 Running Shoes ($500 budget, CPC $0.50)
✅ Created ad: "Ultraboost 24 — 30% off!"
✅ Created developer: TestBot
✅ Searched ads for "running shoes" → 1 result (relevance 0.95)
✅ Reported impression → $0.00 charged (CPC model)
✅ Reported click → $0.50 charged, developer earned $0.35
✅ Analytics: 1 impression, 1 click, $0.50 spent, $0.35 developer revenue

开发者如何获得付款

当你的 MCP 服务器报告 CPC 广告的点击事件时,出价的 70% 归你——在我们的数据库中原子性地记录。一旦你的余额达到 $10,请发送邮件至 payouts@agentic-ads.com,提供你的 developer_id 和首选付款方式(PayPal 或 Polygon 上的 USDC)。我们验证你的余额并在 5 个工作日内付款。当网络规模扩大后,自动 Stripe 付款已在路线图中。


常见问题

面向开发者

问:如何获取 API 密钥? 答:通过 REST 端点注册:

curl -X POST https://agentic-ads-production.up.railway.app/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Your Name", "email": "you@example.com"}'
# Returns: { "developer_id": "...", "api_key": "aa_dev_...", "mcp_url": "..." }

在 MCP 请求中使用返回的 api_key 作为 Authorization: Bearer aa_dev_...。

问:我必须展示广告吗? 答:不。你可以控制展示哪些广告。只有当广告确实为用户增加价值时才展示。代理的自主性是一个特性。

问:如果我的用户讨厌广告怎么办? 答:遵循 get_ad_guidelines 中的指南:每个响应最多 1-2 个广告,始终注明“赞助”,尊重选择退出(“请不要展示广告”)。

问:这可以用于生产环境吗? 答:可以。270 个测试通过,在 https://agentic-ads-production.up.railway.app 运行,采用 MIT 许可证。

问:支持哪些 MCP 客户端? 答:任何支持 stdio 或 Streamable HTTP 的 MCP 客户端。已在 Claude Desktop、Cursor、Windsurf、自定义代理上测试。

面向广告主

问:如何创建广告? 答:使用广告主 API 密钥调用 create_campaign 和 create_ad MCP 工具。示例请参见 smoke-test.ts。

问:我的预算如何受到保护? 答:预算追踪是原子性的(SQLite 事务)。当预算耗尽时 → 广告活动自动暂停。不会超支。

问:我可以追踪转化吗? 答:可以,使用 CPA 定价模式 + 带有 event_type: 'conversion' 的 report_event。在链接 URL 中添加 UTM 参数以进行归因。

问:有哪些定位选项? 答:MVP 支持关键词(精确 + 部分匹配)、分类、地理位置(国家级别)和语言。语义匹配将在第二阶段推出。

通用

问:你们会跟踪用户吗? 答:不会。我们只接收来自代理的匿名关键词查询。没有用户 ID、没有 Cookie、没有画像。隐私优先。

问:如何防止欺诈? 答:MVP 使用 API 密钥认证 + 速率限制 + 基于信任的报告。第二阶段将增加异常检测启发式算法(参见 issue #47)。

问:这是开源的吗? 答:是的,MIT 许可证。可以 Fork、自托管、贡献代码。


路线图

  • MVP — 8 个 MCP 工具、关键词匹配、计费、认证、270 个测试

  • 已部署 — 上线地址 https://agentic-ads-production.up.railway.app

  • 市场列表 — 提交至 Anthropic Registry、Smithery、Glama、PulseMCP(第 1 周)

  • 仪表盘 REST API — 面向广告主/开发者的 Web 界面(#40)

  • 欺诈检测 — 异常启发式算法(#47)

  • 语义匹配 — 基于嵌入向量的相关性(第二阶段)

  • A/B 测试 — 广告创意变体(#41)

  • Stripe 付款 — 自动化开发者支付(第三阶段)


贡献指南

我们遵循 GitHub Issues 工作流程:

  1. 检查你的想法是否已有对应 Issue

  2. 如果没有:gh issue create --title "你的想法"

  3. 开始工作前获得批准

  4. 分支命名:feature/#N-描述

  5. 提交信息:feat(#N): 描述

  6. 向 main 分支提交 PR

详细指南请参阅 CLAUDE.md。


文档


支持


许可证

MIT — 详见 LICENSE。


为什么这很重要

AI 代理正在吞噬互联网。用户不再搜索 Google,而是向代理提问。代理回应,而非网站。

旧互联网: 用户浏览网站 → 看到广告 → 广告主触达用户。

新互联网: 用户向代理提问 → 代理爬取网站 → 广告主无法触达用户。

agentic-ads 解决了这个问题。 它是代理经济中的广告层。

而你——作为 MCP 开发者——作为中间人可以获得 70% 的收入分成。

机遇: 超过 16,000 个 MCP 服务器,几乎没有实现盈利。你可以成为第一个。


基于 Model Context Protocol (MCP) 构建——连接 AI 代理与工具的开源标准。

在线演示: https://agentic-ads-production.up.railway.app

开始上手: 将 MCP 服务器添加到你的配置中,本周即可赚取第一美元。

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    A Model Context Protocol (MCP) server that gives Claude Desktop direct access to your Google AdSense account. Ask plain English questions about your revenue — no dashboard required.
    10
    13 npm
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    MCP server for Google AdSense management. Create ad units, generate framework-specific ad code, manage earnings reports, and automate ads.txt — all from your AI assistant.
    12
    13 npm
    MIT