# TikTok Ads MCP
A comprehensive Model Context Protocol (MCP) server for interacting with the TikTok Business API. This package provides a complete interface to manage TikTok advertising campaigns, ad groups, ads, and generate detailed performance reports.
## Features
- **Complete TikTok Business API Integration**: Access all major TikTok advertising endpoints
- **6 Comprehensive Tools**: Business centers, ad accounts, campaigns, ad groups, ads, and reports
- **Advanced Filtering**: Powerful filtering options for all data retrieval operations
- **Multi-Advertiser Support**: Handle multiple advertiser accounts in a single request
- **Flexible Reporting**: Generate detailed performance reports with custom dimensions and metrics
- **Real-time Data**: Access live advertising data and performance metrics
- **Error Handling**: Comprehensive error handling and validation
- **Modular Architecture**: Clean, maintainable code structure
## Available Tools
1. **get_business_centers** - Retrieve business centers accessible by your access token
2. **get_authorized_ad_accounts** - Get all authorized advertiser accounts
3. **get_campaigns** - Retrieve campaigns with comprehensive filtering options
4. **get_ad_groups** - Get ad groups with advanced filtering and targeting options
5. **get_ads** - Retrieve ads with detailed creative and performance data
6. **get_reports** - Generate comprehensive performance reports and analytics
## Quick Start
### Installation
```bash
# Clone the repository
git clone https://github.com/ysntony/tiktok-ads-mcp.git
cd tiktok-ads-mcp
# Install in development mode
pip install -e .
```
### Configuration
1. **Set up environment variables** in your MCP client configuration:
```json
{
"mcpServers": {
"tiktok-ads": {
"command": "/path/to/your/python",
"args": ["-m", "tiktok_ads_mcp"],
"cwd": "/path/to/tiktok-ads-mcp",
"env": {
"TIKTOK_APP_ID": "your_app_id",
"TIKTOK_SECRET": "your_secret",
"TIKTOK_ACCESS_TOKEN": "your_access_token",
"TIKTOK_ADVERTISER_ID": "your_advertiser_id"
}
}
}
}
```
2. **Required credentials**:
- `TIKTOK_APP_ID`: Your TikTok app ID
- `TIKTOK_SECRET`: Your TikTok app secret
- `TIKTOK_ACCESS_TOKEN`: Your access token
- `TIKTOK_ADVERTISER_ID`: Your advertiser ID (optional)
### Usage
Once configured, you can use the MCP tools through your MCP client (like Cursor, Claude Desktop, etc.):
- Get business centers and advertiser accounts
- Retrieve campaigns, ad groups, and ads with filtering
- Generate detailed performance reports
- Access real-time advertising data
## Project Structure
```
tiktok_ads_mcp/
├── client.py # Core API client
├── config.py # Configuration management
├── server.py # MCP server implementation
├── tools/ # Individual tool implementations
│ ├── __init__.py
│ ├── get_business_centers.py
│ ├── get_authorized_ad_accounts.py
│ ├── get_campaigns.py
│ ├── get_ad_groups.py
│ ├── get_ads.py
│ └── reports.py
└── __main__.py # Entry point for module execution
```
## API Coverage
This MCP server provides comprehensive coverage of the TikTok Business API:
### Business Management
- Business center retrieval and management
- Advertiser account access and permissions
### Campaign Management
- Campaign creation, retrieval, and filtering
- Campaign status and performance monitoring
- Budget and objective management
### Ad Group Management
- Ad group creation and retrieval
- Advanced targeting and optimization settings
- Performance monitoring and filtering
### Ad Management
- Ad creation and retrieval
- Creative asset management
- Performance tracking and optimization
### Reporting & Analytics
- Basic performance reports
- Audience insights reports
- Playable ads reports
- DSA (Dynamic Search Ads) reports
- Business Center reports
- GMV max ads reports
## Key Features
### Advanced Filtering
All tools support comprehensive filtering options:
- Status-based filtering (active, paused, deleted)
- Time-based filtering (creation date, modification date)
- Performance-based filtering (budget, optimization goals)
- Creative filtering (ad formats, material types)
### Multi-Advertiser Support
- Handle multiple advertiser accounts in single requests
- Cross-advertiser reporting and analytics
- Unified data access across accounts
### Flexible Reporting
- Custom dimensions and metrics
- Multiple report types and data levels
- Time-based and lifetime metrics
- Aggregated and detailed views
### Error Handling
- Comprehensive parameter validation
- Detailed error messages and suggestions
- Graceful handling of API limitations
- Rate limiting and retry logic
## Development
### Prerequisites
- Python 3.8+
- TikTok Business API access
- Valid API credentials
### Local Development
```bash
# Install development dependencies
python setup_dev.py
# Run tests
python -m pytest tests/
# Test MCP server
python test_mcp_server.py
```
### Adding New Tools
1. Create new tool file in `tiktok_ads_mcp/tools/`
2. Add function signature and implementation
3. Update `tools/__init__.py`
4. Add tool definition in `server.py`
5. Test the implementation
## Documentation
- **MCP_USAGE.md**: Comprehensive usage guide with examples
- **TikTok Business API**: Official API documentation
- **Project Wiki**: Additional resources and guides
## Contributing
1. Fork the repository
2. Create a feature branch
3. Implement your changes
4. Add tests and documentation
5. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
For issues and questions:
1. Check the [MCP_USAGE.md](MCP_USAGE.md) documentation
2. Review the [TikTok Business API documentation](https://developers.tiktok.com/doc/login-kit-web)
3. Open an issue on the GitHub repository
4. Contact the development team
## Changelog
### v0.1.1 (Current)
- Complete implementation of all 6 tools
- Advanced filtering and reporting capabilities
- Multi-advertiser support
- Comprehensive error handling
- Modular tools architecture
- Complete documentation and usage guides
### v0.1.0
- Initial release with basic MCP server structure
- Core API client implementation
- Basic authentication and configuration
---
*Built with ❤️ for the growth marketing community*
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, model-context-protocol, tiktok",
"author": null,
"author_email": "Yu Shengnan <yushengnan0525@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/77/12/148103a97d037f52cabf3e68c6f2b3b793666f49457899b26ab4916e0f99/tiktok_ads_mcp-0.1.1.tar.gz",
"platform": null,
"description": "# TikTok Ads MCP\n\nA comprehensive Model Context Protocol (MCP) server for interacting with the TikTok Business API. This package provides a complete interface to manage TikTok advertising campaigns, ad groups, ads, and generate detailed performance reports.\n\n## Features\n\n- **Complete TikTok Business API Integration**: Access all major TikTok advertising endpoints\n- **6 Comprehensive Tools**: Business centers, ad accounts, campaigns, ad groups, ads, and reports\n- **Advanced Filtering**: Powerful filtering options for all data retrieval operations\n- **Multi-Advertiser Support**: Handle multiple advertiser accounts in a single request\n- **Flexible Reporting**: Generate detailed performance reports with custom dimensions and metrics\n- **Real-time Data**: Access live advertising data and performance metrics\n- **Error Handling**: Comprehensive error handling and validation\n- **Modular Architecture**: Clean, maintainable code structure\n\n## Available Tools\n\n1. **get_business_centers** - Retrieve business centers accessible by your access token\n2. **get_authorized_ad_accounts** - Get all authorized advertiser accounts\n3. **get_campaigns** - Retrieve campaigns with comprehensive filtering options\n4. **get_ad_groups** - Get ad groups with advanced filtering and targeting options\n5. **get_ads** - Retrieve ads with detailed creative and performance data\n6. **get_reports** - Generate comprehensive performance reports and analytics\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/ysntony/tiktok-ads-mcp.git\ncd tiktok-ads-mcp\n\n# Install in development mode\npip install -e .\n```\n\n### Configuration\n\n1. **Set up environment variables** in your MCP client configuration:\n\n```json\n{\n \"mcpServers\": {\n \"tiktok-ads\": {\n \"command\": \"/path/to/your/python\",\n \"args\": [\"-m\", \"tiktok_ads_mcp\"],\n \"cwd\": \"/path/to/tiktok-ads-mcp\",\n \"env\": {\n \"TIKTOK_APP_ID\": \"your_app_id\",\n \"TIKTOK_SECRET\": \"your_secret\",\n \"TIKTOK_ACCESS_TOKEN\": \"your_access_token\",\n \"TIKTOK_ADVERTISER_ID\": \"your_advertiser_id\"\n }\n }\n }\n}\n```\n\n2. **Required credentials**:\n - `TIKTOK_APP_ID`: Your TikTok app ID\n - `TIKTOK_SECRET`: Your TikTok app secret\n - `TIKTOK_ACCESS_TOKEN`: Your access token\n - `TIKTOK_ADVERTISER_ID`: Your advertiser ID (optional)\n\n### Usage\n\nOnce configured, you can use the MCP tools through your MCP client (like Cursor, Claude Desktop, etc.):\n\n- Get business centers and advertiser accounts\n- Retrieve campaigns, ad groups, and ads with filtering\n- Generate detailed performance reports\n- Access real-time advertising data\n\n## Project Structure\n\n```\ntiktok_ads_mcp/\n\u251c\u2500\u2500 client.py # Core API client\n\u251c\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 server.py # MCP server implementation\n\u251c\u2500\u2500 tools/ # Individual tool implementations\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 get_business_centers.py\n\u2502 \u251c\u2500\u2500 get_authorized_ad_accounts.py\n\u2502 \u251c\u2500\u2500 get_campaigns.py\n\u2502 \u251c\u2500\u2500 get_ad_groups.py\n\u2502 \u251c\u2500\u2500 get_ads.py\n\u2502 \u2514\u2500\u2500 reports.py\n\u2514\u2500\u2500 __main__.py # Entry point for module execution\n```\n\n## API Coverage\n\nThis MCP server provides comprehensive coverage of the TikTok Business API:\n\n### Business Management\n- Business center retrieval and management\n- Advertiser account access and permissions\n\n### Campaign Management\n- Campaign creation, retrieval, and filtering\n- Campaign status and performance monitoring\n- Budget and objective management\n\n### Ad Group Management\n- Ad group creation and retrieval\n- Advanced targeting and optimization settings\n- Performance monitoring and filtering\n\n### Ad Management\n- Ad creation and retrieval\n- Creative asset management\n- Performance tracking and optimization\n\n### Reporting & Analytics\n- Basic performance reports\n- Audience insights reports\n- Playable ads reports\n- DSA (Dynamic Search Ads) reports\n- Business Center reports\n- GMV max ads reports\n\n## Key Features\n\n### Advanced Filtering\nAll tools support comprehensive filtering options:\n- Status-based filtering (active, paused, deleted)\n- Time-based filtering (creation date, modification date)\n- Performance-based filtering (budget, optimization goals)\n- Creative filtering (ad formats, material types)\n\n### Multi-Advertiser Support\n- Handle multiple advertiser accounts in single requests\n- Cross-advertiser reporting and analytics\n- Unified data access across accounts\n\n### Flexible Reporting\n- Custom dimensions and metrics\n- Multiple report types and data levels\n- Time-based and lifetime metrics\n- Aggregated and detailed views\n\n### Error Handling\n- Comprehensive parameter validation\n- Detailed error messages and suggestions\n- Graceful handling of API limitations\n- Rate limiting and retry logic\n\n## Development\n\n### Prerequisites\n- Python 3.8+\n- TikTok Business API access\n- Valid API credentials\n\n### Local Development\n```bash\n# Install development dependencies\npython setup_dev.py\n\n# Run tests\npython -m pytest tests/\n\n# Test MCP server\npython test_mcp_server.py\n```\n\n### Adding New Tools\n1. Create new tool file in `tiktok_ads_mcp/tools/`\n2. Add function signature and implementation\n3. Update `tools/__init__.py`\n4. Add tool definition in `server.py`\n5. Test the implementation\n\n## Documentation\n\n- **MCP_USAGE.md**: Comprehensive usage guide with examples\n- **TikTok Business API**: Official API documentation\n- **Project Wiki**: Additional resources and guides\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Implement your changes\n4. Add tests and documentation\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nFor issues and questions:\n1. Check the [MCP_USAGE.md](MCP_USAGE.md) documentation\n2. Review the [TikTok Business API documentation](https://developers.tiktok.com/doc/login-kit-web)\n3. Open an issue on the GitHub repository\n4. Contact the development team\n\n## Changelog\n\n### v0.1.1 (Current)\n- Complete implementation of all 6 tools\n- Advanced filtering and reporting capabilities\n- Multi-advertiser support\n- Comprehensive error handling\n- Modular tools architecture\n- Complete documentation and usage guides\n\n### v0.1.0\n- Initial release with basic MCP server structure\n- Core API client implementation\n- Basic authentication and configuration\n\n---\n\n*Built with \u2764\ufe0f for the growth marketing community*",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol (MCP) plugin for interacting with TikTok Ads API",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/ysntony/tiktok-ads-mcp/issues",
"Changelog": "https://github.com/ysntony/tiktok-ads-mcp/blob/main/README.md#changelog",
"Documentation": "https://github.com/ysntony/tiktok-ads-mcp#readme",
"Homepage": "https://github.com/ysntony/tiktok-ads-mcp",
"Repository": "https://github.com/ysntony/tiktok-ads-mcp"
},
"split_keywords": [
"ads",
" advertising",
" api",
" marketing",
" mcp",
" model-context-protocol",
" tiktok"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "77a882849c7481d870435dbfea4b4cbe1fb9856092aea17170582648533c7111",
"md5": "16f0f6ddb6a32b2158b3206a97bb24b9",
"sha256": "4c5f8881601e27ac1c505b0282d254c02ae82a99f4a46d8172af51f81372f081"
},
"downloads": -1,
"filename": "tiktok_ads_mcp-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "16f0f6ddb6a32b2158b3206a97bb24b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20903,
"upload_time": "2025-07-27T09:08:46",
"upload_time_iso_8601": "2025-07-27T09:08:46.051319Z",
"url": "https://files.pythonhosted.org/packages/77/a8/82849c7481d870435dbfea4b4cbe1fb9856092aea17170582648533c7111/tiktok_ads_mcp-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7712148103a97d037f52cabf3e68c6f2b3b793666f49457899b26ab4916e0f99",
"md5": "bbeeaf04a52d96824f3e058c54cd1261",
"sha256": "45dca65975886baf5f03c9804da2e07698c0bee9a1235b2eaa4ecabad65e8a59"
},
"downloads": -1,
"filename": "tiktok_ads_mcp-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "bbeeaf04a52d96824f3e058c54cd1261",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18125,
"upload_time": "2025-07-27T09:08:47",
"upload_time_iso_8601": "2025-07-27T09:08:47.401522Z",
"url": "https://files.pythonhosted.org/packages/77/12/148103a97d037f52cabf3e68c6f2b3b793666f49457899b26ab4916e0f99/tiktok_ads_mcp-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 09:08:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ysntony",
"github_project": "tiktok-ads-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.32.3"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "mcp",
"specs": [
[
">=",
"1.9.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.2.0"
]
]
}
],
"lcname": "tiktok-ads-mcp"
}
JSON
