| Name | tiktok-ads-mcp JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Model Context Protocol (MCP) plugin for interacting with TikTok Ads API |
| upload_time | 2025-07-24 14:23:10 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
ads
advertising
api
marketing
mcp
tiktok
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# TikTok Ads MCP Server
A **pure MCP (Model Context Protocol)** server for TikTok Business API integration, designed for AI-first interactions. Inspired by the [meta-ads-mcp](https://github.com/pipeboard-co/meta-ads-mcp.git) project architecture.
## 🎯 **Pure MCP Architecture**
This project follows the **pure MCP server design philosophy**:
- **AI-First**: Designed specifically for AI model consumption.
- **Single Interface**: MCP protocol only - no extra CLI, web UI, or other human interfaces.
- **Lightweight**: Minimal dependencies defined in `pyproject.toml` for core functionality.
- **Production-Ready**: Enterprise-grade reliability and error handling.
## 🚀 **Key Features**
### 🔐 **Enhanced Authentication System**
- **Robust Local Authentication** - Secure `.env`-based credential management.
- **Token Validation** - Comprehensive API credential validation on startup.
- **Smart Caching** - Performance-optimized response caching.
- **Rate Limiting** - Built-in API rate limiting protection.
### 🛡️ **Production-Ready Error Handling**
- **Custom Exception Types** - `TikTokAuthenticationError` and `TikTokAPIError`.
- **Detailed Error Messages** - Clear error descriptions with actionable suggestions.
- **Graceful Degradation** - Server starts even with invalid credentials, flagging the issue clearly.
- **Comprehensive Logging** - Debug-friendly logging system.
## 🔧 Installation & Setup
1. **Clone the repository**:
```bash
git clone <repository-url>
cd tiktok-ads-mcp
```
2. **Set up environment variables**:
Copy the example environment file. This is where you will store your secret credentials.
```bash
cp .env.example .env
```
Edit the `.env` file with your TikTok API credentials. **This file is git-ignored and will not be shared.**
```bash
# Required TikTok API credentials
TIKTOK_APP_ID="your_app_id_here"
TIKTOK_SECRET="your_app_secret_here"
TIKTOK_ACCESS_TOKEN="your_access_token_here"
# Optional performance settings
TOKEN_CACHE_ENABLED=true
TIKTOK_API_RATE_LIMIT=1000
TIKTOK_REQUEST_TIMEOUT=30
```
3. **Install the package**:
Install the project in "editable" mode. This command reads the `pyproject.toml` file, installs all dependencies, and makes the `tiktok-ads-mcp` command available in your terminal.
```bash
pip install -e .
```
## 🚀 Usage
### **1. Running as a Command (Recommended)**
After installation, you can run the MCP server from anywhere with a single command:
```bash
tiktok-ads-mcp
```
### **2. Running for Development**
For development or testing, you can also run the server directly from the example script without installation:
```bash
python examples/basic_usage.py
```
### **3. MCP Client Integration**
Configure your MCP client (like Claude Desktop) to use the installed command. This is the most robust method.
```JSON
{
"mcpServers": {
"tiktok-ads": {
"command": "tiktok-ads-mcp",
"args": [],
}
}
}
```
## 📋 Available MCP Tools
This server exposes several tools for interacting with the TikTok Ads API.
-- **get_advertisers** - Get all advertiser accounts.
-- **get_campaigns** - Get campaigns with optional filters.
-- **get_insights** - Get performance insights and metrics.
-- **health_check** - Check API connectivity and server health.
-- **validate_token** - Validate API credentials and return account info.
-- **get_auth_info** - Get comprehensive authentication status.
For a detailed guide on all function parameters, return values, and use cases, please see the MCP Usage Guide.
## 🏗️ Project Structure
tiktok-ads-mcp/
├── tiktok_ads_mcp/ # The main Python package
│ ├── __init__.py # Package initialization
│ ├── server.py # Core MCP server implementation
│ ├── client.py # TikTok API client logic
│ ├── config.py # Configuration management (.env loader)
│ └── main.py # Command-line entry point
├── examples/ # Usage examples
│ └── basic_usage.py
├── .gitignore # Files to be ignored by Git
├── LICENSE # Project License
├── MCP_USAGE.md # Detailed function documentation
├── pyproject.toml # Project definition and dependencies
├── .env.template # Template for environment variables
└── README.md # This file
## 🤝 Contributing
-- **Fork the repository.**
-- **Create a feature branch.**
-- **Add comprehensive tests for your changes.**
-- **Ensure all code is formatted and passes linting checks.**
-- **Submit a pull request with a clear description of your changes.**
## 📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "tiktok-ads-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ads, advertising, api, marketing, mcp, tiktok",
"author": null,
"author_email": "Yu Shengnan <yushengnan0525@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/cc/12/3cb2fcc2ce0525e45f5168c71a28b7ad4d36c92cf3068c3570155fc28ceb/tiktok_ads_mcp-0.1.0.tar.gz",
"platform": null,
"description": "# TikTok Ads MCP Server\n\nA **pure MCP (Model Context Protocol)** server for TikTok Business API integration, designed for AI-first interactions. Inspired by the [meta-ads-mcp](https://github.com/pipeboard-co/meta-ads-mcp.git) project architecture.\n\n## \ud83c\udfaf **Pure MCP Architecture**\n\nThis project follows the **pure MCP server design philosophy**:\n- **AI-First**: Designed specifically for AI model consumption.\n- **Single Interface**: MCP protocol only - no extra CLI, web UI, or other human interfaces.\n- **Lightweight**: Minimal dependencies defined in `pyproject.toml` for core functionality.\n- **Production-Ready**: Enterprise-grade reliability and error handling.\n\n## \ud83d\ude80 **Key Features**\n\n### \ud83d\udd10 **Enhanced Authentication System**\n- **Robust Local Authentication** - Secure `.env`-based credential management.\n- **Token Validation** - Comprehensive API credential validation on startup.\n- **Smart Caching** - Performance-optimized response caching.\n- **Rate Limiting** - Built-in API rate limiting protection.\n\n### \ud83d\udee1\ufe0f **Production-Ready Error Handling**\n- **Custom Exception Types** - `TikTokAuthenticationError` and `TikTokAPIError`.\n- **Detailed Error Messages** - Clear error descriptions with actionable suggestions.\n- **Graceful Degradation** - Server starts even with invalid credentials, flagging the issue clearly.\n- **Comprehensive Logging** - Debug-friendly logging system.\n\n## \ud83d\udd27 Installation & Setup\n\n1. **Clone the repository**:\n ```bash\n git clone <repository-url>\n cd tiktok-ads-mcp\n ```\n\n2. **Set up environment variables**:\n Copy the example environment file. This is where you will store your secret credentials.\n ```bash\n cp .env.example .env\n ```\n Edit the `.env` file with your TikTok API credentials. **This file is git-ignored and will not be shared.**\n ```bash\n # Required TikTok API credentials\n TIKTOK_APP_ID=\"your_app_id_here\"\n TIKTOK_SECRET=\"your_app_secret_here\"\n TIKTOK_ACCESS_TOKEN=\"your_access_token_here\"\n\n # Optional performance settings\n TOKEN_CACHE_ENABLED=true\n TIKTOK_API_RATE_LIMIT=1000\n TIKTOK_REQUEST_TIMEOUT=30\n ```\n\n3. **Install the package**:\n Install the project in \"editable\" mode. This command reads the `pyproject.toml` file, installs all dependencies, and makes the `tiktok-ads-mcp` command available in your terminal.\n ```bash\n pip install -e .\n ```\n\n## \ud83d\ude80 Usage\n\n### **1. Running as a Command (Recommended)**\n\nAfter installation, you can run the MCP server from anywhere with a single command:\n```bash \ntiktok-ads-mcp\n```\n\n### **2. Running for Development**\n\nFor development or testing, you can also run the server directly from the example script without installation:\n```bash\npython examples/basic_usage.py\n```\n\n### **3. MCP Client Integration**\nConfigure your MCP client (like Claude Desktop) to use the installed command. This is the most robust method.\n```JSON\n{\n \"mcpServers\": {\n \"tiktok-ads\": {\n \"command\": \"tiktok-ads-mcp\",\n \"args\": [],\n }\n }\n}\n```\n\n## \ud83d\udccb Available MCP Tools\nThis server exposes several tools for interacting with the TikTok Ads API.\n\n-- **get_advertisers** - Get all advertiser accounts.\n-- **get_campaigns** - Get campaigns with optional filters.\n-- **get_insights** - Get performance insights and metrics.\n-- **health_check** - Check API connectivity and server health.\n-- **validate_token** - Validate API credentials and return account info.\n-- **get_auth_info** - Get comprehensive authentication status.\nFor a detailed guide on all function parameters, return values, and use cases, please see the MCP Usage Guide.\n\n## \ud83c\udfd7\ufe0f Project Structure\ntiktok-ads-mcp/\n\u251c\u2500\u2500 tiktok_ads_mcp/ # The main Python package\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 server.py # Core MCP server implementation\n\u2502 \u251c\u2500\u2500 client.py # TikTok API client logic\n\u2502 \u251c\u2500\u2500 config.py # Configuration management (.env loader)\n\u2502 \u2514\u2500\u2500 main.py # Command-line entry point\n\u251c\u2500\u2500 examples/ # Usage examples\n\u2502 \u2514\u2500\u2500 basic_usage.py\n\u251c\u2500\u2500 .gitignore # Files to be ignored by Git\n\u251c\u2500\u2500 LICENSE # Project License\n\u251c\u2500\u2500 MCP_USAGE.md # Detailed function documentation\n\u251c\u2500\u2500 pyproject.toml # Project definition and dependencies\n\u251c\u2500\u2500 .env.template # Template for environment variables\n\u2514\u2500\u2500 README.md # This file\n\n## \ud83e\udd1d Contributing\n-- **Fork the repository.**\n-- **Create a feature branch.**\n-- **Add comprehensive tests for your changes.**\n-- **Ensure all code is formatted and passes linting checks.**\n-- **Submit a pull request with a clear description of your changes.**\n\n## \ud83d\udcc4 License\nThis project is licensed under the MIT License - see the LICENSE file for details.",
"bugtrack_url": null,
"license": null,
"summary": "Model Context Protocol (MCP) plugin for interacting with TikTok Ads API",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/yushengnan0525/tiktok-ads-mcp#readme",
"Homepage": "https://github.com/yushengnan0525/tiktok-ads-mcp",
"Repository": "https://github.com/yushengnan0525/tiktok-ads-mcp"
},
"split_keywords": [
"ads",
" advertising",
" api",
" marketing",
" mcp",
" tiktok"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5edbe118fa22f81ed26a60716a167b9e215bea70bee407e06af070fbab3640a7",
"md5": "e6d4e62153ee122826ce7ae8aab4c705",
"sha256": "dab9ea9524103165c62eef76cb93feff763e27faaa32bdebf628d174dc7fc23c"
},
"downloads": -1,
"filename": "tiktok_ads_mcp-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e6d4e62153ee122826ce7ae8aab4c705",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14425,
"upload_time": "2025-07-24T14:23:08",
"upload_time_iso_8601": "2025-07-24T14:23:08.901635Z",
"url": "https://files.pythonhosted.org/packages/5e/db/e118fa22f81ed26a60716a167b9e215bea70bee407e06af070fbab3640a7/tiktok_ads_mcp-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cc123cb2fcc2ce0525e45f5168c71a28b7ad4d36c92cf3068c3570155fc28ceb",
"md5": "203d74e48ea0c15b70249169a2795846",
"sha256": "fe517322cb7ee2b73fd5876ab4b5ccb1194359c180d5cc443c0f3ddf612f5710"
},
"downloads": -1,
"filename": "tiktok_ads_mcp-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "203d74e48ea0c15b70249169a2795846",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14034,
"upload_time": "2025-07-24T14:23:10",
"upload_time_iso_8601": "2025-07-24T14:23:10.349164Z",
"url": "https://files.pythonhosted.org/packages/cc/12/3cb2fcc2ce0525e45f5168c71a28b7ad4d36c92cf3068c3570155fc28ceb/tiktok_ads_mcp-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 14:23:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yushengnan0525",
"github_project": "tiktok-ads-mcp#readme",
"github_not_found": true,
"lcname": "tiktok-ads-mcp"
}
