Troubleshooting
First stop, always: open /setup — the dashboard shows what is connected and any problem
in plain words, and every source has a Test button. In Claude, ask "Run list_sources".
| Symptom | Cause | Fix |
|---|---|---|
| Claude says the connector can't connect / asks for OAuth | Wrong URL or Authentication not set to None | Copy the URL again from the dashboard; Authentication → None. |
| Setup page doesn't load / certificate error | DNS not pointing at the server, or port 80/443 closed | Check the A record and the firewall; wait a minute after the first start. |
| "Google rejected the saved token (invalid_grant)" | Google disconnected you — usually because the OAuth consent screen is in Testing (7-day limit) or the password changed | Publish the consent screen (or set it to Internal), then /setup → Google → Reconnect Google. |
Google Ads Test shows DEVELOPER_TOKEN_NOT_APPROVED |
The developer token still has Test-account access | Google Ads (manager account) → Tools → API Center → apply for / check Basic access. Real accounts return this error until Google approves. |
Google Ads Test shows USER_PERMISSION_DENIED |
The accounts sit under a manager (MCC) account but no MCC id (or the wrong one) is set — or the connected Google user can't see them | /setup → Google → enter the 10-digit MCC id the accounts sit under → Save → Test. Otherwise reconnect Google with a user who sees the accounts in ads.google.com. |
Google Ads Test shows CUSTOMER_NOT_ENABLED or CUSTOMER_NOT_FOUND |
A selected account is cancelled, or an id is mistyped | /setup → Google → Choose accounts → untick or correct it. |
Google Ads Test shows REQUESTED_METRICS_FOR_MANAGER |
A manager (MCC) account was selected instead of its client accounts | Choose the client accounts under it (the MCC itself has no campaigns). |
Google Ads Test shows DEVELOPER_TOKEN_PROHIBITED |
The Google Cloud project is tied to a different developer token | Use that token, or create the OAuth client in a new Cloud project. |
| Meta "Invalid OAuth access token" | Token expired or pasted incompletely | Generate a new system-user token (expiry: Never) and paste it again. |
| Meta insights empty for an account | The system user wasn't assigned that ad account | Business settings → System users → Assign assets. |
| LinkedIn error 426 | The API version is no longer supported | /setup → LinkedIn Ads → set a newer version (YYYYMM) → Save. |
| LinkedIn "reconnect" notice | Refresh token expiring | Click Reconnect LinkedIn. |
| Shopify "rejected the access token" | Token wrong or app uninstalled | Reinstall the custom app and paste the new token. |
| Shopify shows only 60 days of orders | Missing read_all_orders scope |
Add the scope in the app, reinstall, paste the new token. |
| Salesforce "login failed" | Client-credentials flow not enabled, no Run-As user, or the app is not active yet | Re-check the Connected App steps; wait 10 minutes after saving changes. |
Salesforce leads all show source: other |
LeadSource mapping not set | /setup → Salesforce → Save mapping. |
| "License: GRACE / EXPIRED" | Subscription lapsed or license service unreachable | Renew; /setup → License → Check now. |
| Write tools say "switched OFF" | Not enabled | /setup → Write tools. |
| Forgot the admin password | — | Edit ADMIN_PASSWORD in ~/marketing-mcp/.env, docker compose up -d. |
Logs
cd ~/marketing-mcp && docker compose logs --tail=200 mcp
Getting help
Send your vendor: the symptom, the time it happened, and the last 200 log lines. Never send
.env or any token.