[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"tool-cohnen--mcp-google-ads":3,"similar-cohnen--mcp-google-ads":51},{"id":4,"github_repo":5,"name":6,"description_en":7,"description_zh":8,"ai_summary_zh":8,"readme_en":9,"readme_zh":10,"quickstart_zh":11,"use_case_zh":12,"hero_image_url":13,"owner_login":14,"owner_name":15,"owner_avatar_url":16,"owner_bio":15,"owner_company":15,"owner_location":15,"owner_email":15,"owner_twitter":15,"owner_website":15,"owner_url":17,"languages":18,"stars":23,"forks":24,"last_commit_at":25,"license":26,"difficulty_score":27,"env_os":28,"env_gpu":29,"env_ram":29,"env_deps":30,"category_tags":37,"github_topics":41,"view_count":45,"oss_zip_url":15,"oss_zip_packed_at":15,"status":46,"created_at":47,"updated_at":48,"faqs":49,"releases":50},6722,"cohnen\u002Fmcp-google-ads","mcp-google-ads","An MCP tool that connects Google Ads with Claude AI\u002FCursor and others, allowing you to analyze your advertising data through natural language conversations. This integration gives you access to campaign information, performance metrics, keyword analytics, and ad management—all through simple chat with Claude, Cursor or Windsurf.","mcp-google-ads 是一款连接 Google Ads 与 Claude AI、Cursor 等智能助手的开源工具，旨在让用户通过自然语言对话轻松分析广告数据。它解决了传统广告后台操作复杂、数据提取门槛高以及报表制作耗时的痛点，将繁琐的查询过程转化为简单的聊天互动。\n\n这款工具特别适合数字营销从业者、广告优化师以及希望利用 AI 提升工作效率的数据分析师使用。用户无需编写复杂的查询代码，只需向 AI 提问，即可快速获取账户概览、活动表现、关键词分析及广告素材效果等关键信息。其独特亮点在于深度集成了 Google Ads 查询语言（GAQL），不仅能精准提取多维度数据，还能驱动 AI 直接生成可视化图表，帮助用户直观洞察趋势。此外，它支持预算监控与出价策略分析，能提供具体的优化建议。通过标准的 MCP 架构，mcp-google-ads 在确保数据安全认证的前提下，实现了广告管理与人工智能的无缝协作，让数据决策变得更加高效且直观。","[![MseeP.ai Security Assessment Badge](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcohnen_mcp-google-ads_readme_ab4ac3877f0e.png)](https:\u002F\u002Fmseep.ai\u002Fapp\u002Fcohnen-mcp-google-ads)\n\n# Google Ads MCP\n\n![Google Ads MCP](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcohnen_mcp-google-ads_readme_4101f4f292e4.jpeg)\n\nA tool that connects [Google Ads](https:\u002F\u002Fads.google.com\u002F) with Claude AI, allowing you to analyze your advertising data through natural language conversations. This integration gives you access to campaign information, performance metrics, keyword analytics, and ad management—all through simple chat with Claude.\n\n---\n\n## What Can This Tool Do For Advertising Professionals?\n\n1. **Account Management**  \n   - See all your Google Ads accounts in one place\n   - Get account details and basic campaign information\n\n2. **Campaign Analytics & Reporting**  \n   - Discover which campaigns are performing best\n   - Track impressions, clicks, conversions, and cost metrics\n   - Analyze performance trends over time\n   - Compare different time periods to spot changes\n   - **Visualize your data** with charts and graphs created by Claude\n\n3. **Keyword & Ad Performance**  \n   - Identify top and underperforming keywords\n   - Analyze ad copy effectiveness \n   - Check quality scores and competitive metrics\n   - Get actionable insights on how to improve your campaigns\n\n4. **Budget & Bid Management**  \n   - Monitor campaign budgets and spending\n   - Analyze bid strategies and performance\n   - Identify opportunities for optimization\n   - Get recommendations for budget allocation\n\n---\n\n## Google Ads MCP Architecture Flow\n\n```mermaid\nflowchart TB\n    User(User) -->|Interacts with| Claude\n    Claude(Claude AI Assistant) -->|Makes requests to| MCP[Google Ads MCP Server]\n    User -->|Can also use| Cursor[Cursor AI Code Editor]\n    Cursor -->|Makes requests to| MCP\n    \n    subgraph \"MCP Server\"\n        FastMCP[FastMCP Server] \n        Tools[Available Tools]\n        Auth[Authentication]\n        \n        FastMCP -->|Exposes| Tools\n        FastMCP -->|Uses| Auth\n    end\n    \n    subgraph \"Google Ads Tools\"\n        ListAccounts[list_accounts]\n        ExecuteGAQL[execute_gaql_query]\n        CampaignPerf[get_campaign_performance]\n        AdPerf[get_ad_performance]\n        RunGAQL[run_gaql]\n    end\n    \n    Tools -->|Includes| ListAccounts\n    Tools -->|Includes| ExecuteGAQL\n    Tools -->|Includes| CampaignPerf\n    Tools -->|Includes| AdPerf\n    Tools -->|Includes| RunGAQL\n    \n    subgraph \"Authentication\"\n        OAuth[OAuth 2.0 Client ID]\n        ServiceAccount[Service Account]\n        Credentials[Google Ads API Credentials]\n        \n        OAuth -->|Provides| Credentials\n        ServiceAccount -->|Provides| Credentials\n    end\n    \n    MCP -->|Communicates with| GoogleAdsAPI[Google Ads API]\n    GoogleAdsAPI -->|Returns| AdData[Advertising Data]\n    AdData -->|Analyzed by| Claude\n    AdData -->|Visualized by| Claude\n    AdData -->|Can be used by| Cursor\n    \n    Credentials -->|Authorizes| GoogleAdsAPI\n    \n    subgraph \"Configuration\"\n        EnvVars[Environment Variables]\n        ConfigFiles[Configuration Files]\n        \n        EnvVars -->|Configures| MCP\n        ConfigFiles -->|Configures| Claude\n        ConfigFiles -->|Configures| Cursor\n    end\n```\n\n## Available Tools\n\nHere's what you can ask Claude to do once you've set up this integration:\n\n| **What You Can Ask For**        | **What It Does**                                            | **What You'll Need to Provide**                                 |\n|---------------------------------|-------------------------------------------------------------|----------------------------------------------------------------|\n| `list_accounts`                 | Shows all your Google Ads accounts                          | Nothing - just ask!                                             |\n| `execute_gaql_query`            | Runs a Google Ads Query Language query                      | Your account ID and a GAQL query                               |\n| `get_campaign_performance`      | Shows campaign metrics with performance data                | Your account ID and time period                                 |\n| `get_ad_performance`            | Detailed analysis of your ad creative performance           | Your account ID and time period                                 |\n| `run_gaql`                      | Runs any arbitrary GAQL query with formatting options       | Your account ID, query, and format (table, JSON, or CSV)        |\n\n### Using the Advanced Query Tools\n\nThe `run_gaql` tool is especially powerful as it allows you to run any custom Google Ads Query Language (GAQL) query. Here are some example queries you can use:\n\n### Example 1: Basic campaign metrics\n\n```sql\nSELECT \n    campaign.name, \n    metrics.clicks, \n    metrics.impressions \nFROM campaign \nWHERE segments.date DURING LAST_7DAYS\n```\n\n### Example 2: Ad group performance\n\n```sql\nSELECT \n    ad_group.name, \n    metrics.conversions, \n    metrics.cost_micros \nFROM ad_group \nWHERE metrics.clicks > 100\n```\n\n### Example 3: Keyword analysis\n\n```sql\nSELECT \n    keyword.text, \n    metrics.average_position, \n    metrics.ctr \nFROM keyword_view \nORDER BY metrics.impressions DESC\n```\n\n*For a complete list of all available tools and their detailed descriptions, ask Claude to \"list tools\" after setup.*\n\n---\n\n## Getting Started (No Coding Experience Required!)\n\n### 1. Set Up Google Ads API Access\n\nBefore using this tool, you'll need to create API credentials that allow Claude to access your Google Ads data. You can choose between two authentication methods:\n\n#### Option A: OAuth 2.0 Client ID (User Authentication)\n\nBest for individual users or desktop applications:\n\n1. Go to the [Google Cloud Console](https:\u002F\u002Fconsole.cloud.google.com\u002F)\n2. Create a new project or select an existing one\n3. Enable the Google Ads API\n4. Go to \"Credentials\" → \"Create Credentials\" → \"OAuth Client ID\"\n5. Choose \"Desktop Application\" as the application type\n6. Download the OAuth client configuration file (client_secret.json)\n7. Create a Google Ads API Developer token (see below)\n\n#### Option B: Service Account (Server-to-Server Authentication)\n\nBetter for automated systems or managing multiple accounts:\n\n1. Go to the [Google Cloud Console](https:\u002F\u002Fconsole.cloud.google.com\u002F)\n2. Create a new project or select an existing one\n3. Enable the Google Ads API\n4. Go to \"Credentials\" → \"Create Credentials\" → \"Service Account\"\n5. Download the service account key file (JSON)\n6. Grant the service account access to your Google Ads accounts\n7. Create a Google Ads API Developer token (see below)\n\n#### Authentication Token Refreshing\n\nThe application now includes robust token refresh handling:\n\n- **OAuth 2.0 Tokens**: The tool will automatically refresh expired OAuth tokens when possible, or prompt for re-authentication if the refresh token is invalid.\n- **Service Account Tokens**: Service account tokens are automatically generated and refreshed as needed without user intervention.\n\n#### Authentication Method Comparison\n\nChoose OAuth 2.0 Client ID if:\n\n- You're building a desktop application\n- Users need to explicitly grant access\n- You're managing a single account or a few personal accounts\n- You want users to have control over access permissions\n\nChoose Service Account if:\n\n- You're building an automated system\n- You need server-to-server authentication\n- You're managing multiple accounts programmatically\n- You don't want\u002Fneed user interaction for authentication\n- You need automatic token refreshing without user intervention\n\n#### Getting a Developer Token\n\n1. Sign in to your Google Ads account at [https:\u002F\u002Fads.google.com](https:\u002F\u002Fads.google.com)\n2. Click on Tools & Settings (wrench icon) in the top navigation\n3. Under \"Setup\", click \"API Center\"\n4. If you haven't already, accept the Terms of Service\n5. Click \"Apply for token\" \n6. Fill out the application form with details about how you plan to use the API\n7. Submit the application and wait for approval (usually 1-3 business days)\n\nNote: Initially, you'll get a test Developer Token that has some limitations. Once you've tested your implementation, you can apply for a production token that removes these restrictions.\n\n### Understanding the Login Customer ID\n\nThe `GOOGLE_ADS_LOGIN_CUSTOMER_ID` is optional and is primarily used when:\n\n- You're working with a Google Ads Manager Account (MCC)\n- You need to access multiple client accounts under that manager account\n\nThe Login Customer ID should be your Manager Account ID (format: XXX-XXX-XXXX) if:\n\n- You're accessing multiple accounts under a manager account\n- You want to use manager account credentials to access client accounts\n\nYou can skip this setting if:\n\n- You're only accessing a single Google Ads account\n- You're using credentials directly from the account you want to access\n\nTo find your Manager Account ID:\n\n1. Sign in to your Google Ads Manager Account\n2. Click on the settings icon (gear)\n3. Your Manager Account ID will be displayed in the format XXX-XXX-XXXX\n4. Download the credentials file (a JSON file)\n\n**🎬 Watch this beginner-friendly tutorial on Youtube:**\nCOMING SOON\n\n### 2. Install Required Software\n\nYou'll need to install these tools on your computer:\n\n- [Python](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F) (version 3.11 or newer) - This runs the connection between Google Ads and Claude\n- [Node.js](https:\u002F\u002Fnodejs.org\u002Fen) - Required for running the MCP inspector and certain MCP components\n- [Claude Desktop](https:\u002F\u002Fclaude.ai\u002Fdownload) - The AI assistant you'll chat with\n\nMake sure both Python and Node.js are properly installed and available in your system path before proceeding.\n\n### 3. Download the Google Ads MCP \n\nYou need to download this tool to your computer. The easiest way is:\n\n1. Click the green \"Code\" button at the top of this page\n2. Select \"Download ZIP\"\n3. Unzip the downloaded file to a location you can easily find (like your Documents folder)\n\nAlternatively, if you're familiar with Git:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fixigo\u002Fmcp-google-ads.git\n```\n\n### 4. Install Required Components\n\nOpen your computer's Terminal (Mac) or Command Prompt (Windows):\n\n1. Navigate to the folder where you unzipped the files:\n\n   ```bash\n   # Example (replace with your actual path):\n   cd ~\u002FDocuments\u002Fmcp-google-ads-main\n   ```\n\n2. Create a virtual environment (this keeps the project dependencies isolated):\n\n   ```bash\n   # Using uv (recommended):\n   uv venv .venv\n   \n   # If uv is not installed, install it first:\n   pip install uv\n   # Then create the virtual environment:\n   uv venv .venv\n\n   # OR using standard Python:\n   python -m venv .venv\n   ```\n\n   **Note:** If you get a \"pip not found\" error when trying to install uv, see the \"If you get 'pip not found' error\" section below.\n\n3. Activate the virtual environment:\n\n   ```bash\n   # On Mac\u002FLinux:\n   source .venv\u002Fbin\u002Factivate\n   \n   # On Windows:\n   .venv\\Scripts\\activate\n   ```\n\n4. Install the required dependencies:\n\n   ```bash\n   # Using uv:\n   uv pip install -r requirements.txt\n\n   # OR using standard pip:\n   pip install -r requirements.txt\n   \n   # If you encounter any issues with the MCP package, install it separately:\n   pip install mcp\n   ```\n\n   **If you get \"pip not found\" error:**\n\n   ```bash\n   # First ensure pip is installed and updated:\n   python3 -m ensurepip --upgrade\n   python3 -m pip install --upgrade pip\n   \n   # Then try installing the requirements again:\n   python3 -m pip install -r requirements.txt\n   \n   # Or to install uv:\n   python3 -m pip install uv\n   ```\n\nWhen you see `(.venv)` at the beginning of your command prompt, it means the virtual environment is active and the dependencies will be installed there without affecting your system Python installation.\n\n### 5. Setting Up Environment Configuration\n\nThe Google Ads MCP now supports environment file configuration for easier setup.\n\n#### Using .env File (Recommended)\n\n1. Copy the `.env.example` file to `.env` in your project directory:\n\n   ```bash\n   cp .env.example .env\n   ```\n\n2. Edit the `.env` file with your actual configuration values:\n\n   ```bash\n   # Edit the .env file with your favorite text editor\n   # For Mac:\n   nano .env\n   \n   # For Windows:\n   notepad .env\n   ```\n\n3. Set the following values in your `.env` file:\n\n   ```\n   # Authentication Type: \"oauth\" or \"service_account\"\n   GOOGLE_ADS_AUTH_TYPE=oauth\n   \n   # Path to your credentials file (OAuth client secret or service account key)\n   GOOGLE_ADS_CREDENTIALS_PATH=\u002Fpath\u002Fto\u002Fyour\u002Fcredentials.json\n   \n   # Your Google Ads Developer Token\n   GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here\n   \n   # Optional: Manager Account ID (if applicable)\n   GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id\n   ```\n\n4. Save the file.\n\nThe application will automatically load these values from the `.env` file when it starts.\n\n#### Using Direct Environment Variables\n\nYou can also set environment variables directly in your system or in the configuration files for Claude or Cursor:\n\n##### For Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"googleAdsServer\": {\n      \"command\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002F.venv\u002Fbin\u002Fpython\",\n      \"args\": [\"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fgoogle_ads_server.py\"],\n      \"env\": {\n        \"GOOGLE_ADS_AUTH_TYPE\": \"oauth\",\n        \"GOOGLE_ADS_CREDENTIALS_PATH\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fcredentials.json\",\n        \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n        \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n      }\n    }\n  }\n}\n```\n\n##### For Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"googleAdsServer\": {\n      \"command\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002F.venv\u002Fbin\u002Fpython\",\n      \"args\": [\"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fgoogle_ads_server.py\"],\n      \"env\": {\n        \"GOOGLE_ADS_AUTH_TYPE\": \"oauth\",\n        \"GOOGLE_ADS_CREDENTIALS_PATH\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fcredentials.json\",\n        \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n        \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n      }\n    }\n  }\n}\n```\n\n### 6. Connect Claude to Google Ads\n\n1. Download and install [Claude Desktop](https:\u002F\u002Fclaude.ai\u002Fdownload) if you haven't already\n2. Make sure you have your Google service account credentials file saved somewhere on your computer\n3. Open your computer's Terminal (Mac) or Command Prompt (Windows) and type:\n\n```bash\n# For Mac users:\nnano ~\u002FLibrary\u002FApplication\\ Support\u002FClaude\u002Fclaude_desktop_config.json\n\n# For Windows users:\nnotepad %APPDATA%\\Claude\\claude_desktop_config.json\n```\n\nAdd the following text (this tells Claude how to connect to Google Ads):\n\n```json\n{\n  \"mcpServers\": {\n    \"googleAdsServer\": {\n      \"command\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002F.venv\u002Fbin\u002Fpython\",\n      \"args\": [\"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fgoogle_ads_server.py\"],\n      \"env\": {\n        \"GOOGLE_ADS_CREDENTIALS_PATH\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fservice_account_credentials.json\",\n        \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n        \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n      }\n    }\n  }\n}\n```\n\n**Important:** Replace all paths and values with the actual information for your account:\n\n- The first path should point to the Python executable inside your virtual environment\n- The second path should point to the `google_ads_server.py` file inside the folder you unzipped\n- The third path should point to your Google service account credentials JSON file\n- Add your Google Ads Developer Token \n- Add your Google Ads Manager Account ID (if applicable)\n\nExamples:\n\n- Mac: \n  - Python path: `\u002FUsers\u002Fernesto\u002FDocuments\u002Fmcp-google-ads\u002F.venv\u002Fbin\u002Fpython`\n  - Script path: `\u002FUsers\u002Fernesto\u002FDocuments\u002Fmcp-google-ads\u002Fgoogle_ads_server.py`\n- Windows: \n  - Python path: `C:\\\\Users\\\\ernesto\\\\Documents\\\\mcp-google-ads\\\\.venv\\\\Scripts\\\\python.exe`\n  - Script path: `C:\\\\Users\\\\ernesto\\\\Documents\\\\mcp-google-ads\\\\google_ads_server.py`\n\n4. Save the file:\n\n   - Mac: Press Ctrl+O, then Enter, then Ctrl+X to exit\n   - Windows: Click File > Save, then close Notepad\n\n5. Restart Claude Desktop\n\n6. When Claude opens, you should now see Google Ads tools available in the tools section\n\n### 5a. Connect to Cursor (AI Code Editor)\n\nCursor is an AI-powered code editor that can be enhanced with MCP tools. You can integrate this Google Ads MCP tool with Cursor to analyze advertising data directly within your coding environment.\n\n#### Setting Up Cursor Integration\n\n1. If you haven't already, download and install [Cursor](https:\u002F\u002Fcursor.sh\u002F) \n2. Create a Cursor MCP configuration file:\n\n   **For project-specific configuration:**\n   Create a `.cursor\u002Fmcp.json` file in your project directory.\n\n   **For global configuration (available in all projects):**\n   Create a `~\u002F.cursor\u002Fmcp.json` file in your home directory.\n\n3. Add the following configuration to your MCP config file:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"googleAdsServer\": {\n         \"command\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002F.venv\u002Fbin\u002Fpython\",\n         \"args\": [\"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fgoogle_ads_server.py\"],\n         \"env\": {\n           \"GOOGLE_ADS_CREDENTIALS_PATH\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fservice_account_credentials.json\",\n           \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n           \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n         }\n       }\n     }\n   }\n   ```\n\n   **Important:** Replace all paths and values with the actual information for your account, just like in the Claude Desktop configuration.\n\n4. Restart Cursor or reload the workspace to apply the new configuration.\n\n5. The Google Ads MCP will now appear in Cursor's \"Available Tools\" section and can be used by Cursor's AI agent when needed.\n\n#### Using Google Ads MCP in Cursor\n\nWhen working in Cursor, you can ask the AI agent to use the Google Ads tools directly. For example:\n\n- \"Use the Google Ads MCP to list all my accounts and show me which ones have the highest spend.\"\n- \"Can you analyze my campaign performance for the last 30 days using the Google Ads MCP?\"\n- \"Run a GAQL query to find my top converting keywords using the Google Ads tools.\"\n\nCursor will prompt you to approve the tool usage (unless you've enabled Yolo mode) and then display the results directly in the chat interface.\n\n#### Cursor-Specific Features\n\nWhen using the Google Ads MCP with Cursor, you can:\n\n1. **Combine Code and Ads Analysis**: Ask Cursor to analyze your marketing-related code alongside actual campaign performance data.\n2. **Generate Data Visualizations**: Request charts and visualizations of your ad performance directly in your development environment.\n3. **Implement Recommendations**: Let Cursor suggest code improvements based on your actual advertising data.\n\nThis integration is particularly valuable for developers working on marketing automation, analytics dashboards, or e-commerce applications where ad performance directly impacts code decisions.\n\n### 6. Start Analyzing Your Advertising Data!\n\nNow you can ask Claude questions about your Google Ads data! Claude can not only retrieve the data but also analyze it, explain trends, and create visualizations to help you understand your advertising performance better.\n\nHere are some powerful prompts you can use with each tool:\n\n| **Tool Name**                   | **Sample Prompt**                                                                                |\n|---------------------------------|--------------------------------------------------------------------------------------------------|\n| `list_accounts`                 | \"List all my Google Ads accounts and tell me which ones have the highest spend this month.\"      |\n| `execute_gaql_query`            | \"Execute this query for account 123-456-7890: SELECT campaign.name, metrics.clicks FROM campaign WHERE metrics.impressions > 1000\" |\n| `get_campaign_performance`      | \"Show me the top 10 campaigns for account 123-456-7890 in the last 30 days, highlight any with ROAS below 2, and suggest optimization strategies.\" |\n| `get_ad_performance`            | \"Do a comprehensive analysis of which ad copy elements are driving the best CTR in my search campaigns and give me actionable recommendations.\" |\n| `run_gaql`                      | \"Run this query and format it as a CSV: SELECT ad_group.name, metrics.clicks, metrics.conversions FROM ad_group WHERE campaign.name LIKE '%Brand%'\" |\n\nYou can also ask Claude to combine multiple tools and analyze the results. For example:\n\n- \"Find my top 20 converting keywords, check their quality scores and impression share, and create a report highlighting opportunities for scaling.\"\n\n- \"Analyze my account's performance trend over the last 90 days, identify my fastest-growing campaigns, and check if there are any budget limitations holding them back.\"\n\n- \"Compare my desktop vs. mobile ad performance, visualize the differences with charts, and recommend specific campaigns that need mobile bid adjustments based on performance gaps.\"\n\n- \"Identify campaigns where I'm spending the most on search terms that aren't in my keyword list, then suggest which ones should be added as exact match keywords.\"\n\nClaude will use the Google Ads tools to fetch the data, present it in an easy-to-understand format, create visualizations when helpful, and provide actionable insights based on the results.\n\n---\n\n## Data Visualization Capabilities\n\nClaude can help you visualize your Google Ads data in various ways:\n\n- **Trend Charts**: See how metrics change over time\n- **Comparison Graphs**: Compare different campaigns or ad groups\n- **Performance Distributions**: Understand how your ads perform across devices or audiences\n- **Correlation Analysis**: Identify relationships between spend and conversion metrics\n- **Heatmaps**: Visualize complex datasets with color-coded representations\n\nSimply ask Claude to \"visualize\" or \"create a chart\" when analyzing your data, and it will generate appropriate visualizations to help you understand the information better.\n\n---\n\n## Troubleshooting\n\n### Python Command Not Found\n\nOn macOS, the default Python command is often `python3` rather than `python`, which can cause issues with some applications including Node.js integrations.\n\nIf you encounter errors related to Python not being found, you can create an alias:\n\n1. Create a Python alias (one-time setup):\n   ```bash\n   # For macOS users:\n   sudo ln -s $(which python3) \u002Fusr\u002Flocal\u002Fbin\u002Fpython\n   \n   # If that doesn't work, try finding your Python installation:\n   sudo ln -s \u002FLibrary\u002FFrameworks\u002FPython.framework\u002FVersions\u002F3.11\u002Fbin\u002Fpython3 \u002Fusr\u002Flocal\u002Fbin\u002Fpython\n   ```\n\n2. Verify the alias works:\n\n   ```bash\n   python --version\n   ```\n\nThis creates a symbolic link so that when applications call `python`, they'll actually use your `python3` installation.\n\n### Claude Configuration Issues\n\nIf you're having trouble connecting:\n\n1. Make sure all file paths in your configuration are correct and use the full path\n2. Check that your service account has access to your Google Ads accounts\n3. Verify that your Developer Token is valid and correctly entered\n4. Restart Claude Desktop after making any changes\n5. Look for error messages in Claude's response when you try to use a tool\n6. Ensure your virtual environment is activated when running the server manually\n\n### Google Ads API Limitations\n\nIf you encounter issues related to API quotas or permissions:\n\n1. Check your Google Ads API quota limits in the Google Cloud Console\n2. Ensure your Developer Token has the appropriate access level\n3. Verify that you've granted the proper permissions to your service account\n\n### Other Unexpected Issues\n\nIf you encounter any other unexpected issues during installation or usage:\n\n1. Copy the exact error message you're receiving\n2. Contact Ernesto Cohnen at ernesto@ixigo.com for support, including:\n   - What you were trying to do\n   - The exact error message\n   - Your operating system\n   - Any steps you've already tried\n\nYou can also consult AI assistants which can often help diagnose and resolve technical issues by suggesting specific solutions for your situation.\n\nRemember that most issues have been encountered by others before, and there's usually a straightforward solution available.\n\n### Testing Your Setup\n\nThe repository includes test files that let you verify your Google Ads API connection is working correctly before using it with Claude or Cursor.\n\n#### Testing Basic Functionality\n\n1. Make sure your virtual environment is activated:\n\n   ```bash\n   # On Mac\u002FLinux:\n   source .venv\u002Fbin\u002Factivate\n   \n   # On Windows:\n   .venv\\Scripts\\activate\n   ```\n\n2. Configure the environment variables in the test file or set them in your environment:\n   - Open `test_google_ads_mcp.py` in a text editor\n   - Find the section starting with `if not os.environ.get(\"GOOGLE_ADS_CREDENTIALS_PATH\"):`\n   - Update the placeholder values with your actual credentials or comment out this section if you've set them as environment variables\n\n3. Run the test:\n   ```bash\n   python test_google_ads_mcp.py\n   ```\n\n4. The test will:\n   - List all your Google Ads accounts\n   - Use the first account ID to test campaign performance retrieval\n   - Test ad performance data\n   - Retrieve ad creatives\n   - Run a sample GAQL query\n\n#### Testing Authentication and Token Refresh\n\nTo specifically test the authentication and token refresh mechanisms:\n\n1. Make sure your virtual environment is activated and your `.env` file is configured.\n\n2. Run the token refresh test:\n   ```bash\n   python test_token_refresh.py\n   ```\n\n3. This test will:\n   - Verify that credentials can be loaded from your configured auth type (OAuth or service account)\n   - Display information about the current token status and expiry\n   - Test the customer ID formatting function\n   - For OAuth tokens, attempt to refresh the token and verify it worked\n\nThe token refresh test can help confirm that both OAuth and service account credentials are properly configured before using the server with Claude or Cursor.\n   \nIf all tests complete successfully, your setup is working correctly and ready to use with Claude or Cursor.\n\n---\n\n## Contributing\n\nFound a bug or have an idea for improvement? We welcome your input! Open an issue or submit a pull request on GitHub, or contact Ernesto Cohnen directly at [ernesto@ixigo.com](mailto:ernesto@ixigo.com).\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## About ixigo\n\nixigo is India's leading travel app, helping millions of travelers find the best deals on flights, trains, buses, and hotels. For more information, visit [ixigo.com](https:\u002F\u002Fwww.ixigo.com).\n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcohnen_mcp-google-ads_readme_d1972396a487.png\" alt=\"ixigo logo\" width=\"200px\" \u002F>\n\nixigo is a technology company that builds products to help people find the best deals on flights, trains, buses, and hotels. We're a team of travel enthusiasts who are passionate about making travel more affordable and accessible to everyone.","[![MseeP.ai 安全评估徽章](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcohnen_mcp-google-ads_readme_ab4ac3877f0e.png)](https:\u002F\u002Fmseep.ai\u002Fapp\u002Fcohnen-mcp-google-ads)\n\n# Google Ads MCP\n\n![Google Ads MCP](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcohnen_mcp-google-ads_readme_4101f4f292e4.jpeg)\n\n这是一款将 [Google Ads](https:\u002F\u002Fads.google.com\u002F) 与 Claude AI 相连接的工具，允许您通过自然语言对话来分析广告数据。借助此集成，您可以通过与 Claude 的简单聊天，轻松获取广告系列信息、效果指标、关键词分析以及广告管理等全方位洞察。\n\n---\n\n## 这款工具能为广告从业者带来哪些帮助？\n\n1. **账户管理**  \n   - 在一处集中查看所有 Google Ads 账户  \n   - 获取账户详情及基础广告系列信息  \n\n2. **广告系列分析与报告**  \n   - 发现表现最佳的广告系列  \n   - 跟踪展示次数、点击量、转化率及成本相关指标  \n   - 分析随时间变化的效果趋势  \n   - 对比不同时间段以发现变化  \n   - 使用 Claude 生成的图表和图形直观呈现数据  \n\n3. **关键词与广告效果**  \n   - 确定表现优异与欠佳的关键词  \n   - 分析广告文案的有效性  \n   - 检查质量得分及竞争相关指标  \n   - 获得优化广告系列的实用建议  \n\n4. **预算与出价管理**  \n   - 监控广告系列预算与支出情况  \n   - 分析出价策略及其效果  \n   - 寻找优化机会  \n   - 获得预算分配建议  \n\n---\n\n## Google Ads MCP 架构流程\n\n```mermaid\nflowchart TB\n    User(User) -->|Interacts with| Claude\n    Claude(Claude AI Assistant) -->|Makes requests to| MCP[Google Ads MCP Server]\n    User -->|Can also use| Cursor[Cursor AI Code Editor]\n    Cursor -->|Makes requests to| MCP\n    \n    subgraph \"MCP Server\"\n        FastMCP[FastMCP Server] \n        Tools[Available Tools]\n        Auth[Authentication]\n        \n        FastMCP -->|Exposes| Tools\n        FastMCP -->|Uses| Auth\n    end\n    \n    subgraph \"Google Ads Tools\"\n        ListAccounts[list_accounts]\n        ExecuteGAQL[execute_gaql_query]\n        CampaignPerf[get_campaign_performance]\n        AdPerf[get_ad_performance]\n        RunGAQL[run_gaql]\n    end\n    \n    Tools -->|Includes| ListAccounts\n    Tools -->|Includes| ExecuteGAQL\n    Tools -->|Includes| CampaignPerf\n    Tools -->|Includes| AdPerf\n    Tools -->|Includes| RunGAQL\n    \n    subgraph \"Authentication\"\n        OAuth[OAuth 2.0 Client ID]\n        ServiceAccount[Service Account]\n        Credentials[Google Ads API Credentials]\n        \n        OAuth -->|Provides| Credentials\n        ServiceAccount -->|Provides| Credentials\n    end\n    \n    MCP -->|Communicates with| GoogleAdsAPI[Google Ads API]\n    GoogleAdsAPI -->|Returns| AdData[Advertising Data]\n    AdData -->|Analyzed by| Claude\n    AdData -->|Visualized by| Claude\n    AdData -->|Can be used by| Cursor\n    \n    Credentials -->|Authorizes| GoogleAdsAPI\n    \n    subgraph \"Configuration\"\n        EnvVars[Environment Variables]\n        ConfigFiles[Configuration Files]\n        \n        EnvVars -->|Configures| MCP\n        ConfigFiles -->|Configures| Claude\n        ConfigFiles -->|Configures| Cursor\n    end\n```\n\n## 可用工具\n\n在完成集成设置后，您可以向 Claude 提出以下请求：\n\n| **可询问内容**        | **功能描述**                                            | **所需信息**                                 |\n|---------------------------------|-------------------------------------------------------------|----------------------------------------------------------------|\n| `list_accounts`                 | 显示您的所有 Google Ads 账户                          | 无需提供任何信息 - 直接提问即可！                                             |\n| `execute_gaql_query`            | 执行 Google Ads 查询语言查询                      | 您的账户 ID 和 GAQL 查询                               |\n| `get_campaign_performance`      | 展示包含效果数据的广告系列指标                | 您的账户 ID 和时间范围                                 |\n| `get_ad_performance`            | 详细分析您的广告创意表现           | 您的账户 ID 和时间范围                                 |\n| `run_gaql`                      | 执行任意 GAQL 查询，并支持格式化输出       | 您的账户 ID、查询语句以及输出格式（表格、JSON 或 CSV）        |\n\n### 高级查询工具的使用方法\n\n`run_gaql` 工具功能强大，允许您运行任何自定义的 Google Ads 查询语言 (GAQL) 查询。以下是一些示例查询：\n\n### 示例 1：基础广告系列指标\n\n```sql\nSELECT \n    campaign.name, \n    metrics.clicks, \n    metrics.impressions \nFROM campaign \nWHERE segments.date DURING LAST_7DAYS\n```\n\n### 示例 2：广告组表现\n\n```sql\nSELECT \n    ad_group.name, \n    metrics.conversions, \n    metrics.cost_micros \nFROM ad_group \nWHERE metrics.clicks > 100\n```\n\n### 示例 3：关键词分析\n\n```sql\nSELECT \n    keyword.text, \n    metrics.average_position, \n    metrics.ctr \nFROM keyword_view \nORDER BY metrics.impressions DESC\n```\n\n*如需查看所有可用工具的完整列表及其详细说明，请在设置完成后让 Claude 执行“列出工具”指令。*\n\n---\n\n## 开始使用（无需编程经验！）\n\n### 1. 设置 Google Ads API 访问权限\n\n在使用本工具之前，您需要创建 API 凭证，以便 Claude 能够访问您的 Google Ads 数据。您可以选择两种身份验证方式：\n\n#### 选项 A：OAuth 2.0 客户端 ID（用户身份验证）\n\n适用于个人用户或桌面应用程序：\n\n1. 前往 [Google Cloud 控制台](https:\u002F\u002Fconsole.cloud.google.com\u002F)  \n2. 创建一个新项目或选择现有项目  \n3. 启用 Google Ads API  \n4. 转到“凭据”→“创建凭据”→“OAuth 客户端 ID”  \n5. 将应用类型选择为“桌面应用”  \n6. 下载 OAuth 客户端配置文件（client_secret.json）  \n7. 创建 Google Ads API 开发者令牌（见下文）\n\n#### 选项 B：服务帐号（服务器到服务器身份验证）\n\n更适合自动化系统或管理多个帐号：\n\n1. 前往 [Google Cloud 控制台](https:\u002F\u002Fconsole.cloud.google.com\u002F)  \n2. 创建一个新项目或选择现有项目  \n3. 启用 Google Ads API  \n4. 转到“凭据”→“创建凭据”→“服务帐号”  \n5. 下载服务帐号密钥文件（JSON）  \n6. 授予服务帐号对您的 Google Ads 帐号的访问权限  \n7. 创建 Google Ads API 开发者令牌（见下文）\n\n#### 身份验证令牌刷新\n\n该应用程序现已包含强大的令牌刷新机制：\n\n- **OAuth 2.0 令牌**：当可能时，工具会自动刷新过期的 OAuth 令牌；如果刷新令牌无效，则会提示重新进行身份验证。\n- **服务帐号令牌**：服务帐号令牌会根据需要自动生成并刷新，无需用户干预。\n\n#### 身份验证方法对比\n\n选择 OAuth 2.0 客户端 ID 的情况：\n\n- 您正在开发桌面应用程序  \n- 用户需要明确授予访问权限  \n- 您只管理单个帐号或少数个人帐号  \n- 您希望用户能够控制访问权限  \n\n选择服务帐号的情况：\n\n- 您正在构建自动化系统  \n- 您需要服务器到服务器的身份验证  \n- 您需要以编程方式管理多个帐号  \n- 您不需要或不希望用户参与身份验证  \n- 您需要自动刷新令牌而无需用户干预  \n\n#### 获取开发者令牌\n\n1. 登录到您的 Google Ads 帐号，网址为 [https:\u002F\u002Fads.google.com](https:\u002F\u002Fads.google.com)  \n2. 在顶部导航栏中点击“工具与设置”（扳手图标）  \n3. 在“设置”部分，点击“API 中心”  \n4. 如果尚未接受，请先同意服务条款  \n5. 点击“申请令牌”  \n6. 填写申请表，说明您计划如何使用 API  \n7. 提交申请并等待批准（通常需要 1–3 个工作日）  \n\n注意：最初您将获得一个测试版开发者令牌，该令牌存在一些限制。在完成实施测试后，您可以申请正式版令牌，以解除这些限制。\n\n### 关于登录客户 ID 的说明\n\n`GOOGLE_ADS_LOGIN_CUSTOMER_ID` 是可选参数，主要用于以下场景：\n\n- 您正在使用 Google Ads 管理帐号（MCC）  \n- 您需要访问该管理帐号下的多个客户帐号  \n\n登录客户 ID 应填写您的管理帐号 ID（格式：XXX-XXX-XXXX），前提是：\n\n- 您要访问管理帐号下的多个帐号  \n- 您希望使用管理帐号凭据来访问客户帐号  \n\n如果您仅访问单个 Google Ads 帐号，或者直接使用目标帐号的凭据，则可以跳过此设置。\n\n查找管理帐号 ID 的步骤：\n\n1. 登录您的 Google Ads 管理帐号  \n2. 点击设置图标（齿轮）  \n3. 您的管理帐号 ID 会以 XXX-XXX-XXXX 的格式显示  \n4. 下载凭据文件（JSON 格式）  \n\n**🎬 观看此面向初学者的 YouTube 教程：**  \n即将推出\n\n### 2. 安装所需软件\n\n您需要在计算机上安装以下工具：\n\n- [Python](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F)（版本 3.11 或更高）：用于运行 Google Ads 与 Claude 之间的连接  \n- [Node.js](https:\u002F\u002Fnodejs.org\u002Fen)：运行 MCP 检查器及某些 MCP 组件所必需  \n- [Claude Desktop](https:\u002F\u002Fclaude.ai\u002Fdownload)：您将与其对话的 AI 助手  \n\n请确保 Python 和 Node.js 已正确安装，并已添加到系统路径中，然后再继续。\n\n### 3. 下载 Google Ads MCP\n\n您需要将此工具下载到本地计算机。最简单的方法是：\n\n1. 点击页面顶部的绿色“代码”按钮  \n2. 选择“下载 ZIP 文件”  \n3. 将下载的文件解压到一个便于查找的位置（例如文档文件夹）  \n\n或者，如果您熟悉 Git：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fixigo\u002Fmcp-google-ads.git\n```\n\n### 4. 安装所需组件\n\n打开计算机上的终端（Mac）或命令提示符（Windows）：\n\n1. 导航到您解压文件的文件夹：\n\n   ```bash\n   # 示例（请替换为您实际的路径）：\n   cd ~\u002FDocuments\u002Fmcp-google-ads-main\n   ```\n\n2. 创建虚拟环境（这将使项目依赖项保持隔离）：\n\n   ```bash\n   # 使用 uv（推荐）：\n   uv venv .venv\n   \n   # 如果未安装 uv，请先安装：\n   pip install uv\n   # 然后再创建虚拟环境：\n   uv venv .venv\n\n   # 或者使用标准 Python：\n   python -m venv .venv\n   ```\n\n   **注意**：如果您在尝试安装 uv 时遇到“pip 未找到”的错误，请参阅下方的“如果出现‘pip 未找到’错误”部分。\n\n3. 激活虚拟环境：\n\n   ```bash\n   # 在 Mac\u002FLinux 上：\n   source .venv\u002Fbin\u002Factivate\n   \n   # 在 Windows 上：\n   .venv\\Scripts\\activate\n   ```\n\n4. 安装所需的依赖项：\n\n   ```bash\n   # 使用 uv：\n   uv pip install -r requirements.txt\n\n   # 或者使用标准 pip：\n   pip install -r requirements.txt\n   \n   # 如果在安装 MCP 包时遇到任何问题，可单独安装：\n   pip install mcp\n   ```\n\n   **如果出现“pip 未找到”错误：**\n\n   ```bash\n   # 首先确保 pip 已安装并更新：\n   python3 -m ensurepip --upgrade\n   python3 -m pip install --upgrade pip\n   \n   # 然后再尝试安装依赖项：\n   python3 -m pip install -r requirements.txt\n   \n   # 或者安装 uv：\n   python3 -m pip install uv\n   ```\n\n当您的命令提示符开头显示 `(.venv)` 时，表示虚拟环境已激活，依赖项将被安装在此环境中，而不会影响您系统的 Python 安装。\n\n### 5. 设置环境配置\n\nGoogle Ads MCP 现在支持通过环境文件进行配置，以简化设置过程。\n\n#### 使用 .env 文件（推荐）\n\n1. 将 `.env.example` 文件复制到项目目录下的 `.env`：\n\n   ```bash\n   cp .env.example .env\n   ```\n\n2. 使用你喜欢的文本编辑器编辑 `.env` 文件，填入实际的配置值：\n\n   ```bash\n   # 在 Mac 上：\n   nano .env\n   \n   # 在 Windows 上：\n   notepad .env\n   ```\n\n3. 在 `.env` 文件中设置以下值：\n\n   ```\n   # 认证类型：“oauth”或“service_account”\n   GOOGLE_ADS_AUTH_TYPE=oauth\n   \n   # 凭证文件路径（OAuth 客户端密钥或服务账号密钥）\n   GOOGLE_ADS_CREDENTIALS_PATH=\u002Fpath\u002Fto\u002Fyour\u002Fcredentials.json\n   \n   # 您的 Google Ads 开发者令牌\n   GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here\n   \n   # 可选：管理帐号 ID（如果适用）\n   GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id\n   ```\n\n4. 保存文件。\n\n应用程序启动时会自动从 `.env` 文件加载这些值。\n\n#### 使用直接环境变量\n\n你也可以直接在系统中或在 Claude 或 Cursor 的配置文件中设置环境变量：\n\n##### 对于 Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"googleAdsServer\": {\n      \"command\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002F.venv\u002Fbin\u002Fpython\",\n      \"args\": [\"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fgoogle_ads_server.py\"],\n      \"env\": {\n        \"GOOGLE_ADS_AUTH_TYPE\": \"oauth\",\n        \"GOOGLE_ADS_CREDENTIALS_PATH\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fcredentials.json\",\n        \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n        \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n      }\n    }\n  }\n}\n```\n\n##### 对于 Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"googleAdsServer\": {\n      \"command\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002F.venv\u002Fbin\u002Fpython\",\n      \"args\": [\"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fgoogle_ads_server.py\"],\n      \"env\": {\n        \"GOOGLE_ADS_AUTH_TYPE\": \"oauth\",\n        \"GOOGLE_ADS_CREDENTIALS_PATH\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fcredentials.json\",\n        \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n        \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n      }\n    }\n  }\n}\n```\n\n### 6. 将 Claude 连接到 Google Ads\n\n1. 如果尚未安装，请下载并安装 [Claude Desktop](https:\u002F\u002Fclaude.ai\u002Fdownload)。\n2. 确保你的 Google 服务账号凭据文件已保存在电脑的某个位置。\n3. 打开电脑的终端（Mac）或命令提示符（Windows），输入以下命令：\n\n   ```bash\n   # 对于 Mac 用户：\n   nano ~\u002FLibrary\u002FApplication\\ Support\u002FClaude\u002Fclaude_desktop_config.json\n\n   # 对于 Windows 用户：\n   notepad %APPDATA%\\Claude\\claude_desktop_config.json\n   ```\n\n   添加以下内容（这将告诉 Claude 如何连接到 Google Ads）：\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"googleAdsServer\": {\n         \"command\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002F.venv\u002Fbin\u002Fpython\",\n         \"args\": [\"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fgoogle_ads_server.py\"],\n         \"env\": {\n           \"GOOGLE_ADS_CREDENTIALS_PATH\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fservice_account_credentials.json\",\n           \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n           \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n         }\n       }\n     }\n   }\n   ```\n\n   **重要提示**：请将所有路径和值替换为你的实际账户信息：\n\n   - 第一个路径应指向虚拟环境中的 Python 可执行文件。\n   - 第二个路径应指向你解压后的文件夹中的 `google_ads_server.py` 文件。\n   - 第三个路径应指向你的 Google 服务账号凭据 JSON 文件。\n   - 添加你的 Google Ads 开发者令牌。\n   - 添加你的 Google Ads 管理帐号 ID（如果适用）。\n\n   示例：\n\n   - Mac：\n     - Python 路径：`\u002FUsers\u002Fernesto\u002FDocuments\u002Fmcp-google-ads\u002F.venv\u002Fbin\u002Fpython`\n     - 脚本路径：`\u002FUsers\u002Fernesto\u002FDocuments\u002Fmcp-google-ads\u002Fgoogle_ads_server.py`\n   - Windows：\n     - Python 路径：`C:\\\\Users\\\\ernesto\\\\Documents\\\\mcp-google-ads\\\\.venv\\\\Scripts\\\\python.exe`\n     - 脚本路径：`C:\\\\Users\\\\ernesto\\\\Documents\\\\mcp-google-ads\\\\google_ads_server.py`\n\n4. 保存文件：\n\n   - Mac：按 Ctrl+O，然后 Enter，最后按 Ctrl+X 退出。\n   - Windows：点击“文件”>“保存”，然后关闭记事本。\n\n5. 重启 Claude Desktop。\n\n6. 当 Claude 打开时，你应该能在工具栏中看到 Google Ads 工具。\n\n### 5a. 连接到 Cursor（AI 代码编辑器）\n\nCursor 是一款由 AI 驱动的代码编辑器，可以通过 MCP 工具进行功能增强。您可以将此 Google Ads MCP 工具与 Cursor 集成，从而在编码环境中直接分析广告数据。\n\n#### 设置 Cursor 集成\n\n1. 如果您尚未安装，请下载并安装 [Cursor](https:\u002F\u002Fcursor.sh\u002F)。\n2. 创建一个 Cursor MCP 配置文件：\n\n   **对于项目特定配置：**\n   在您的项目目录中创建 `.cursor\u002Fmcp.json` 文件。\n\n   **对于全局配置（在所有项目中可用）：**\n   在您的主目录下创建 `~\u002F.cursor\u002Fmcp.json` 文件。\n\n3. 将以下配置添加到您的 MCP 配置文件中：\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"googleAdsServer\": {\n         \"command\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002F.venv\u002Fbin\u002Fpython\",\n         \"args\": [\"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fgoogle_ads_server.py\"],\n         \"env\": {\n           \"GOOGLE_ADS_CREDENTIALS_PATH\": \"\u002FFULL\u002FPATH\u002FTO\u002Fmcp-google-ads-main\u002Fservice_account_credentials.json\",\n           \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n           \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n         }\n       }\n     }\n   }\n   ```\n\n   **重要提示：** 请将所有路径和值替换为您账户的实际信息，就像在 Claude Desktop 配置中一样。\n   \n4. 重启 Cursor 或重新加载工作区以应用新配置。\n   \n5. 现在，Google Ads MCP 将出现在 Cursor 的“可用工具”部分，并可在需要时由 Cursor 的 AI 助手使用。\n\n#### 在 Cursor 中使用 Google Ads MCP\n\n在 Cursor 中工作时，您可以要求 AI 助手直接使用 Google Ads 工具。例如：\n\n- “使用 Google Ads MCP 列出我的所有账户，并告诉我哪些账户的支出最高。”\n- “你能用 Google Ads MCP 分析我过去 30 天的广告系列表现吗？”\n- “运行 GAQL 查询，利用 Google Ads 工具找出我转化率最高的关键词。”\n\nCursor 会提示您批准工具的使用（除非您已启用 Yolo 模式），然后将结果显示在聊天界面中。\n\n#### Cursor 特定功能\n\n当将 Google Ads MCP 与 Cursor 结合使用时，您可以：\n\n1. **结合代码与广告分析**：让 Cursor 同时分析您的营销相关代码和实际的广告系列表现数据。\n2. **生成数据可视化**：直接在开发环境中请求广告表现的图表和可视化效果。\n3. **实施建议**：让 Cursor 根据您的实际广告数据提出代码改进建议。\n\n这种集成对于从事营销自动化、分析仪表盘或电子商务应用开发的开发者尤其有价值，因为广告表现会直接影响代码决策。\n\n### 6. 开始分析您的广告数据吧！\n\n现在您可以向 Claude 提问有关 Google Ads 数据的问题了！Claude 不仅可以检索数据，还能对其进行分析、解释趋势，并创建可视化图表，帮助您更好地理解广告表现。\n\n以下是您可针对每种工具使用的强大提示示例：\n\n| **工具名称**                   | **示例提示**                                                                                |\n|---------------------------------|--------------------------------------------------------------------------------------------------|\n| `list_accounts`                 | “列出我所有的 Google Ads 账户，并告诉我本月哪些账户的支出最高。”      |\n| `execute_gaql_query`            | “为账户 123-456-7890 执行以下查询：SELECT campaign.name, metrics.clicks FROM campaign WHERE metrics.impressions > 1000” |\n| `get_campaign_performance`      | “展示账户 123-456-7890 过去 30 天内排名前 10 的广告系列，突出显示 ROAS 低于 2 的广告，并提出优化策略。” |\n| `get_ad_performance`            | “全面分析我的搜索广告中哪些文案元素带来了最佳点击率，并给出可操作的建议。” |\n| `run_gaql`                      | “运行此查询，并将其格式化为 CSV：SELECT ad_group.name, metrics.clicks, metrics.conversions FROM ad_group WHERE campaign.name LIKE '%Brand%'” |\n\n您还可以要求 Claude 组合使用多种工具并分析结果。例如：\n\n- “找出我转化率最高的 20 个关键词，检查它们的质量得分和展示份额，并生成一份报告，指出可扩展的机会。”\n  \n- “分析我的账户在过去 90 天内的表现趋势，找出增长最快的广告系列，并检查是否存在预算限制阻碍其发展。”\n  \n- “比较我的桌面端与移动端广告表现，用图表展示差异，并推荐需要根据性能差距调整移动端出价的具体广告系列。”\n  \n- “找出那些在非关键词列表中的搜索词上花费最多的广告，然后建议将哪些词添加为完全匹配关键词。”\n\nClaude 将使用 Google Ads 工具获取数据，以易于理解的格式呈现，并在必要时创建可视化图表，同时基于结果提供可操作的见解。\n\n---\n\n## 数据可视化能力\n\nClaude 可以帮助您以多种方式可视化 Google Ads 数据：\n\n- **趋势图**：查看指标随时间的变化情况\n- **对比图**：比较不同的广告系列或广告组\n- **表现分布图**：了解您的广告在不同设备或受众上的表现\n- **相关性分析**：识别花费与转化指标之间的关系\n- **热力图**：通过颜色编码表示复杂的数据集\n\n只需在分析数据时要求 Claude“可视化”或“创建图表”，它就会生成适当的可视化内容，帮助您更好地理解信息。\n\n---\n\n## 故障排除\n\n### Python 命令未找到\n\n在 macOS 上，默认的 Python 命令通常是 `python3` 而不是 `python`，这可能会导致一些应用程序出现问题，包括 Node.js 集成。\n\n如果您遇到与 Python 未找到相关的错误，可以创建一个别名：\n\n1. 创建 Python 别名（一次性设置）：\n   ```bash\n   # 对于 macOS 用户：\n   sudo ln -s $(which python3) \u002Fusr\u002Flocal\u002Fbin\u002Fpython\n   \n   # 如果上述方法无效，请尝试找到您的 Python 安装路径：\n   sudo ln -s \u002FLibrary\u002FFrameworks\u002FPython.framework\u002FVersions\u002F3.11\u002Fbin\u002Fpython3 \u002Fusr\u002Flocal\u002Fbin\u002Fpython\n   ```\n\n2. 验证别名是否生效：\n\n   ```bash\n   python --version\n   ```\n\n通过创建符号链接，当应用程序调用 `python` 时，实际上会使用您的 `python3` 安装版本。\n\n### Claude 配置问题\n\n如果您在连接时遇到困难：\n\n1. 请确保配置文件中的所有文件路径都正确，并使用完整路径。\n2. 检查您的服务账号是否具有访问 Google Ads 账户的权限。\n3. 确认您的开发者令牌有效且输入正确。\n4. 在进行任何更改后，请重启 Claude Desktop。\n5. 当您尝试使用工具时，请查看 Claude 的响应中是否有错误信息。\n6. 手动运行服务器时，请确保已激活虚拟环境。\n\n### Google Ads API 的限制\n\n如果您遇到与 API 配额或权限相关的问题：\n\n1. 请在 Google Cloud 控制台中检查您的 Google Ads API 配额限制。\n2. 确保您的开发者令牌具有适当的访问级别。\n3. 验证您是否已为服务账号授予了正确的权限。\n\n### 其他意外问题\n\n如果您在安装或使用过程中遇到任何其他意外问题：\n\n1. 复制您收到的确切错误信息。\n2. 联系 Ernesto Cohnen，邮箱地址为 ernesto@ixigo.com 寻求支持，提供以下信息：\n   - 您当时正在尝试执行的操作\n   - 确切的错误信息\n   - 您的操作系统\n   - 您已经尝试过的步骤\n\n此外，您也可以咨询 AI 助手，它们通常能够帮助诊断并解决技术问题，为您提供针对您具体情况的解决方案。\n\n请记住，大多数问题之前都曾被其他人遇到过，通常都有一个简单的解决方案。\n\n### 测试您的设置\n\n该仓库包含测试文件，可让您在将 Google Ads API 与 Claude 或 Cursor 集成之前，验证其连接是否正常工作。\n\n#### 测试基本功能\n\n1. 确保已激活虚拟环境：\n\n   ```bash\n   # 在 Mac\u002FLinux 上：\n   source .venv\u002Fbin\u002Factivate\n   \n   # 在 Windows 上：\n   .venv\\Scripts\\activate\n   ```\n\n2. 配置测试文件中的环境变量，或将它们设置在您的环境中：\n   - 使用文本编辑器打开 `test_google_ads_mcp.py`。\n   - 找到以 `if not os.environ.get(\"GOOGLE_ADS_CREDENTIALS_PATH\"):` 开头的部分。\n   - 将占位符值替换为您实际的凭据，或者如果您已将这些凭据设置为环境变量，则注释掉此部分。\n\n3. 运行测试：\n   ```bash\n   python test_google_ads_mcp.py\n   ```\n\n4. 测试将执行以下操作：\n   - 列出您的所有 Google Ads 账户。\n   - 使用第一个账户 ID 测试广告系列效果的获取。\n   - 测试广告效果数据。\n   - 获取广告素材。\n   - 运行一个示例 GAQL 查询。\n\n#### 测试身份验证和令牌刷新\n\n要专门测试身份验证和令牌刷新机制：\n\n1. 确保已激活虚拟环境，并且 `.env` 文件已正确配置。\n2. 运行令牌刷新测试：\n   ```bash\n   python test_token_refresh.py\n   ```\n\n3. 该测试将：\n   - 验证是否可以从您配置的身份验证类型（OAuth 或服务账号）加载凭据。\n   - 显示当前令牌的状态及过期时间。\n   - 测试客户 ID 格式化函数。\n   - 对于 OAuth 令牌，尝试刷新令牌并验证是否成功。\n\n令牌刷新测试可以帮助您确认 OAuth 和服务账号凭据均已正确配置，然后再将服务器与 Claude 或 Cursor 集成使用。\n\n如果所有测试均成功完成，则说明您的设置已正确配置，可以与 Claude 或 Cursor 一起使用了。\n\n---\n\n## 贡献\n\n发现 bug 或有改进建议？我们非常欢迎您的参与！您可以在 GitHub 上提交问题或拉取请求，也可以直接联系 Ernesto Cohnen，邮箱地址为 [ernesto@ixigo.com](mailto:ernesto@ixigo.com)。\n\n---\n\n## 许可证\n\n本项目采用 MIT 许可证授权。详细信息请参阅 [LICENSE](LICENSE) 文件。\n\n---\n\n## 关于 ixigo\n\nixigo 是印度领先的旅行应用，帮助数百万旅客找到最优惠的机票、火车票、巴士票和酒店预订。更多信息请访问 [ixigo.com](https:\u002F\u002Fwww.ixigo.com)。\n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcohnen_mcp-google-ads_readme_d1972396a487.png\" alt=\"ixigo logo\" width=\"200px\" \u002F>\n\nixigo 是一家科技公司，致力于开发帮助人们找到最优惠机票、火车票、巴士票和酒店预订的产品。我们是一支由旅行爱好者组成的团队，热衷于让旅行更加经济实惠、人人可及。","# mcp-google-ads 快速上手指南\n\n`mcp-google-ads` 是一个连接 Google Ads 与 Claude AI 的工具，允许你通过自然语言对话分析广告数据、查看活动表现、关键词分析及管理广告系列。\n\n## 环境准备\n\n在开始之前，请确保你的系统已安装以下软件：\n\n*   **Python**: 版本 3.11 或更高（推荐使用国内镜像源安装依赖）。\n*   **Node.js**: 用于运行 MCP 检查器及部分组件。\n*   **Claude Desktop**: 用于交互的 AI 助手客户端。\n*   **Google Ads API 凭证**: 需提前在 Google Cloud Console 和 Google Ads 后台获取（OAuth Client ID 或服务账号密钥，以及 Developer Token）。\n\n> **提示**：国内开发者在安装 Python 包时，建议使用清华或阿里镜像源加速下载。\n\n## 安装步骤\n\n### 1. 下载项目代码\n\n你可以直接下载 ZIP 包解压，或使用 Git 克隆：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fixigo\u002Fmcp-google-ads.git\ncd mcp-google-ads\n```\n\n### 2. 创建并激活虚拟环境\n\n推荐使用 `uv` 工具（速度快），也可以使用标准 `venv`。\n\n**使用 uv (推荐):**\n```bash\n# 如果未安装 uv\npip install uv -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n\n# 创建虚拟环境\nuv venv .venv\n\n# 激活环境 (Mac\u002FLinux)\nsource .venv\u002Fbin\u002Factivate\n# 激活环境 (Windows)\n.venv\\Scripts\\activate\n```\n\n**使用标准 Python:**\n```bash\npython -m venv .venv\n# 激活环境 (Mac\u002FLinux)\nsource .venv\u002Fbin\u002Factivate\n# 激活环境 (Windows)\n.venv\\Scripts\\activate\n```\n\n### 3. 安装依赖\n\n```bash\n# 使用 uv 安装 (推荐，速度快)\nuv pip install -r requirements.txt -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n\n# 或使用标准 pip\npip install -r requirements.txt -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n\n# 若遇到 MCP 包问题，可单独安装\npip install mcp -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n```\n\n### 4. 配置环境变量\n\n复制示例配置文件并填入你的 Google Ads API 凭证信息：\n\n```bash\ncp .env.example .env\n```\n\n编辑 `.env` 文件，填入以下关键信息（根据你选择的认证方式填写）：\n\n*   `GOOGLE_ADS_DEVELOPER_TOKEN`: 你的开发者令牌。\n*   `GOOGLE_ADS_CLIENT_ID` \u002F `GOOGLE_ADS_CLIENT_SECRET`: OAuth 客户端信息（若选 OAuth）。\n*   `GOOGLE_ADS_SERVICE_ACCOUNT_KEY`: 服务账号密钥文件路径或内容（若选服务账号）。\n*   `GOOGLE_ADS_LOGIN_CUSTOMER_ID`: (可选) 经理账号 (MCC) ID，格式为 `XXX-XXX-XXXX`。如果是单账户直连可留空。\n\n## 基本使用\n\n配置完成后，启动 Claude Desktop 并确保其加载了该 MCP 服务器。你可以在对话框中直接使用自然语言进行查询。\n\n**最简单的使用示例：**\n\n1.  **查看所有账户**\n    在 Claude 对话框中输入：\n    > \"列出我所有的 Google Ads 账户\"\n    *(对应工具：`list_accounts`)*\n\n2.  **查询近期广告系列表现**\n    输入：\n    > \"显示过去 7 天我的广告系列点击量和展示次数\"\n    *(对应工具：`get_campaign_performance`)*\n\n3.  **执行自定义 GAQL 查询**\n    如果你熟悉 SQL 风格的 GAQL 语法，可以直接让 Claude 运行复杂查询：\n    > \"运行一个查询，找出过去 30 天转化率最高的前 5 个关键词，并按转化数降序排列\"\n    \n    Claude 将自动调用 `run_gaql` 工具执行类似以下的逻辑：\n    ```sql\n    SELECT \n        keyword.text, \n        metrics.conversions \n    FROM keyword_view \n    WHERE segments.date DURING LAST_30_DAYS \n    ORDER BY metrics.conversions DESC \n    LIMIT 5\n    ```\n\n4.  **数据可视化**\n    你可以要求：\n    > \"根据上周的数据，画一个展示各广告系列花费趋势的图表\"\n    Claude 将分析数据并生成可视化图表。","某电商公司的广告优化师正在为“黑色星期五”大促做最后的预算调整，急需快速诊断过去一周各广告系列的表现并找出浪费预算的关键词。\n\n### 没有 mcp-google-ads 时\n- **数据获取繁琐**：必须登录 Google Ads 后台，手动切换多个账户和日期范围，反复导出 CSV 报表才能汇总数据。\n- **分析效率低下**：面对成千上万行关键词数据，只能依靠 Excel 透视表缓慢筛选，难以即时发现异常波动的具体原因。\n- **洞察滞后**：从发现某个广告组成本过高到提出优化建议，往往需要数小时的数据清洗时间，错失最佳调整时机。\n- **可视化门槛高**：若想向管理层展示趋势图表，需额外学习 BI 工具或花费大量时间手动制作 PPT 图表。\n\n### 使用 mcp-google-ads 后\n- **对话即查询**：直接在 Claude 或 Cursor 中输入“对比上周‘黑五’预热期各系列的转化率”，mcp-google-ads 即刻调用 API 返回精准数据。\n- **智能归因分析**：让 AI 自动分析表现最差的十个关键词，mcp-google-ads 迅速提供质量得分与竞争指标，直接定位无效流量来源。\n- **实时决策支持**：通过自然语言询问“哪些广告组预算消耗过快但转化低”，立即获得具体的预算重新分配建议并执行调整。\n- **自动生成图表**：只需指令“画出过去 7 天点击成本趋势图”，mcp-google-ads 配合 Claude 瞬间生成可视化图表，无需任何手动绘图操作。\n\nmcp-google-ads 将原本耗时数小时的数据搬运与分析工作压缩为几分钟的自然语言对话，让广告优化师能专注于策略制定而非数据处理。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fcohnen_mcp-google-ads_4101f4f2.jpg","cohnen",null,"https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fcohnen_8429adda.jpg","https:\u002F\u002Fgithub.com\u002Fcohnen",[19],{"name":20,"color":21,"percentage":22},"Python","#3572A5",100,536,119,"2026-04-11T02:11:58","MIT",4,"macOS, Windows, Linux","未说明",{"notes":31,"python":32,"dependencies":33},"需要安装 Node.js 以运行 MCP 检查器及部分组件；需配置 Google Ads API 凭证（OAuth 2.0 或服务账号）及开发者令牌；建议使用虚拟环境（如 .venv）隔离依赖。","3.11+",[34,35,36],"mcp","google-ads","uv",[38,39,40],"Agent","开发框架","图像",[42,43,35,34,44],"ai","claude","mcp-server",2,"ready","2026-03-27T02:49:30.150509","2026-04-12T07:54:58.993371",[],[],[52,62,70,79,87,96],{"id":53,"name":54,"github_repo":55,"description_zh":56,"stars":57,"difficulty_score":58,"last_commit_at":59,"category_tags":60,"status":46},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[38,39,40,61],"数据工具",{"id":63,"name":64,"github_repo":65,"description_zh":66,"stars":67,"difficulty_score":58,"last_commit_at":68,"category_tags":69,"status":46},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[39,40,38],{"id":71,"name":72,"github_repo":73,"description_zh":74,"stars":75,"difficulty_score":45,"last_commit_at":76,"category_tags":77,"status":46},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",151314,"2026-04-11T23:32:58",[39,38,78],"语言模型",{"id":80,"name":81,"github_repo":82,"description_zh":83,"stars":84,"difficulty_score":45,"last_commit_at":85,"category_tags":86,"status":46},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[39,40,38],{"id":88,"name":89,"github_repo":90,"description_zh":91,"stars":92,"difficulty_score":45,"last_commit_at":93,"category_tags":94,"status":46},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[95,38,40,39],"插件",{"id":97,"name":98,"github_repo":99,"description_zh":100,"stars":101,"difficulty_score":45,"last_commit_at":102,"category_tags":103,"status":46},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[95,39]]