AdsPower MCP server
Commit Nov 12, 2026Allows an AI client to control the AdsPower browser via LocalAPI, including managing browser profiles and operating in headless mode.
Also known as AdsPower/adspower-browser
- Stars
- 156
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- MIT
What is AdsPower MCP?
AdsPower allows an AI client to control the AdsPower browser via LocalAPI, including managing browser profiles and operating in headless mode.
Summary generated from the project's README
About AdsPower MCP server
Controlling AdsPower browser profiles through an AI client is what this MCP server enables. It connects AI tools like Claude Code, Cursor, and Codex to the AdsPower LocalAPI, allowing users to manage browser environments directly from their development interface. The setup requires a local installation of AdsPower and a Node.js version of 18 or higher.
Users interact with the server by providing an API key and a port number, which defaults to 50325. The server supports managing browser profiles and can operate in headless mode for automated tasks. It is designed to work with various clients including OpenClaw, Hermes agent, and OpenCode by configuring environment variables or specific JSON settings.
Beyond standard browser management, the package includes a CLI that runs independently from the main client. This CLI can start, stop, or restart the AdsPower service and retrieve browser lists. Developers can also deploy the CLI using Docker for containerized environments.
What you can do with it
- 1Manage browser profilesAsk your AI client to retrieve a list of all available browser profiles from AdsPower.
- 2Automate browser operationsRun browser tasks in the background without a visible user interface using headless mode.
- 3Control AdsPower service statusInstruct an AI agent to check if the AdsPower service is currently running or to restart it.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
API_KEY
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubAdsPower Skill & MCP & CLI
adspower-browser Skill
Claude Code/Codex/Cursor/OpenCode/Gemini GL
npx skills add https://github.com/adspower/adspower-browser --skill adspower-browser
OpenClaw(小龙虾)
npx clawhub@latest install adspower-browser --force
Hermes agent(爱马仕)
hermes skills install https://github.com/AdsPower/adspower-browser/blob/main/skills/adspower-browser --force
AdsPower CLI
The AdsPower CLI is completely isolated from the AdsPower client, runs independently, and does not share local caches/kernels, etc. However, the CLI also supports headless mode for operating the AdsPower client.
npm install -g adspower-browser # 安装
ads start -k <KEY> # 启动 adspower
ads stop # 停止 adspower
ads restart # 重启 adspower
ads status # 查询 adspower 运行状态
ads get-browser-list # 获取配置文件列表
... #查看 https://github.com/AdsPower/adspower-browser/blob/main/packages/adspower-browser/README.MD
AdsPower client headless mode:
AdsPower Global:
Windows: "AdsPower Global.exe" --headless=true --api-key=your_api_key --api-port=50325
MacOS:"/Applications/AdsPower Global.app/Contents/MacOS/AdsPower Global" --args --headless=true --api-key=your_api_key --api-port=50325
Linux:adspower_global --headless=true --api-key=your_api_key --api-port=50325
AdsPower MCP
Claude Code:
claude mcp add adspower-local-api -e PORT="50325" -e API_KEY="your_api_key" -- npx -y local-api-mcp-typescript
Codex:
codex mcp add --env PORT="50325" --env API_KEY="your_api_key" adspower-local-api -- npx -y local-api-mcp-typescript
OpenClaw:
openclaw mcp set adspower-local-api '{"command":"npx","args":["-y","local-api-mcp-typescript"],"env":{"PORT":"50325","API_KEY":"your_api_key"}}'
Cursor: Go to Cursor Settings -> MCP -> Add New MCP Server, and then paste the following content:
{
"mcpServers": {
"adspower-local-api": {
"command": "npx",
"args": ["-y", "local-api-mcp-typescript"],
"env": {
"PORT": "50325",
"API_KEY": "your_api_key"
}
}
}
}
OpenCode: update ~/.config/opencode/opencode.json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"adspower-local-api": {
"command": "npx",
"args": ["-y", "local-api-mcp-typescript"],
"env": {
"PORT": "50325",
"API_KEY": "your_api_key"
}
}
}
}
How to use?
Requirements
-
Node version 18 or greater
Version Compatibility
Some APIs are introduced incrementally by AdsPower client version.
If the client has not been upgraded to a version that includes a specific API, requests may return Not found.
When this happens:
- Upgrade AdsPower client to the latest patch version first.
- Then retry the same command/API.
Port Configuration
The port parameter specifies the AdsPower Local API port. Default is 50325.
Priority order:
- Command-line argument
--port(highest priority) - Environment variable
PORT(medium priority) - Default value
50325(lowest priority)
Examples:
Using command-line argument:
{
"mcpServers": {
"adspower-local-api": {
"command": "npx",
"args": ["-y", "local-api-mcp-typescript", "--port", "50325"]
}
}
}
Using environment variable:
{
"mcpServers": {
"adspower-local-api": {
"command": "npx",
"args": ["-y", "local-api-mcp-typescript"],
"env": {
"PORT": "50325"
}
}
}
}
Development
# clone
git clone https://github.com/AdsPower/adspower-browser.git
cd adspower-browser
# install (monorepo)
pnpm install
# build all packages
pnpm run build
For local MCP development, point Claude Desktop to the MCP package:
"mcpServers": {
"adspower-local-api": {
"command": "node",
"args": ["<Replace Your Project Path>/adspower-browser/packages/local-api-mcp/build/index.js"]
}
}
Use AdsPower Cli in Docker
copy the /packages/adspower-browser/docker-compose.yml
cd packages/adspower-browser
docker-compose -f ./docker-compose.yml up -d
docker-compose exec adspower-cli /bin/bash
AdsPower MCP questions
Can I run AdsPower in headless mode?
Yes, the CLI supports headless mode for operating the AdsPower client.
What should I do if an API returns a 'Not found' error?
You should upgrade your AdsPower client to the latest patch version and then retry the command or API.
How can I configure the API port?
The port can be set via a command-line argument, an environment variable, or it will default to 50325.