Flyweel MCP Setup & Quickstart Guide

Connect your AI to your ads. Ask questions. Get answers.

What Flyweel’s MCP exposes

What Is Flyweel MCP?

Flyweel MCP lets you talk to your ad data.

Instead of clicking through Google Ads or Meta Ads dashboards, you just ask your AI. It looks at your real numbers and tells you what’s happening.

Think of it like this: Your ads live in one house (Google/Meta). Your AI lives in another house (Claude/Cursor). Flyweel MCP is the phone line between them. Now they can talk.

What Do I Need to Get Started?

1. A Flyweel account with your ad accounts connected
2. An AI tool that speaks MCP. Supported today:
   • Claude (web & desktop), Claude Code CLI
   • ChatGPT (requires Developer Mode), Cursor, VS Code, Windsurf, Zed
   • Cline, Continue.dev, JetBrains AI Assistant
   • Codex CLI, Gemini CLI, Warp, Raycast
   • Any other MCP-compliant client

That’s it.

How Do I Set Up Flyweel MCP?

Two steps. Under 5 minutes.

The fastest path is OAuth — no API key to copy, paste, or leak. You connect with one URL, sign in, and approve access. Only headless and CLI-only clients need an API key (see Advanced: Connect with an API key).

Step 1: Connect Your AI Tool via OAuth

The only thing you paste is Flyweel’s server URL:

https://api.flyweel.co/functions/v1/mcp-server/mcp

You’ll be redirected to sign in and approve access. No keys are stored in your AI client.

claude mcp add --transport http flyweel-mcp-server https://api.flyweel.co/functions/v1/mcp-server/mcp

Step 2: Test Your Connection

Ask your AI:

“What Google Ads accounts do I have connected to Flyweel?”

If you see your accounts listed, it works.

Advanced: Connect with an API key

Most users should connect via OAuth above. Use an API key only for headless / CI use, or clients that can’t OAuth (many CLI tools).

"mcpServers": {
  "flyweel-mcp-server": {
    "type": "http",
    "url": "https://api.flyweel.co/functions/v1/mcp-server/mcp",
    "headers": {
      "Authorization": "Bearer fwl_YOUR_TOKEN_HERE"
    }
  }
}

claude mcp add --transport http flyweel-mcp-server https://api.flyweel.co/functions/v1/mcp-server/mcp --header "Authorization: Bearer fwl_YOUR_TOKEN_HERE"

Available Tools

Just talk to your AI like you’re talking to a person. Here’s what works.

How Do I Check My Ad Accounts?

Start here when you first connect:

How Do I Check Ad Performance?

Ask about how your ads are doing:

How Do I Check Ad Spend?

Ask about where your money goes:

How Do I Compare Campaigns?

Ask your AI to compare:

How Do I Check Specific Time Periods?

You can ask about any date range:

How Do I Find Problems?

Ask your AI to spot issues:

How Do I Manage My Data?

You can control syncing and which accounts you’re analyzing:

How Do I Get Better Answers?

Be Specific

Instead of: “How are my ads?”

Try: “What’s my CTR and cost per conversion for my Google Search campaigns this month?”

Name Your Account

If you have multiple accounts, say which one:

Instead of: “Show me my campaigns”

Try: “Show me campaigns in my Main Google Ads account”

Ask Follow-Up Questions

Start broad, then dig in:

1. “Which campaign has the most conversions?”
2. “What’s the cost per conversion for that one?”
3. “How does that compare to last month?”

Ask for Comparisons

Your AI is good at comparing things:

• “Which is better: my Search campaign or my PMAX campaign?”
• “Compare my top 3 campaigns by conversions”
• “Is my Meta or Google account more efficient?”

Ask for Recommendations

Your AI can help you think:

• “Based on this data, which campaign should I scale?”
• “Which campaign should I pause?”
• “Where am I wasting money?”

What Data Can I See?

How Fresh Is My Data?

Your data syncs automatically from Google and Meta:

Need fresher data? Ask your AI: “Sync my Google Ads data” or go to your Flyweel dashboard and click Sync Now.

You can also ask “Is my data syncing?” to check progress.

What Can’t Flyweel MCP Do?

It’s read-only. Your AI can look at your ads. It cannot change them.

It cannot:

• Pause or start campaigns
• Change budgets
• Edit your ads
• Delete anything

Your campaigns are safe.

Other limits:

• One account per question (ask about each account separately)
• Daily numbers only (no hourly breakdown)
• Google Ads, Meta Ads, and TikTok Ads (public release end of April 2026). LinkedIn and X are not supported yet.
• Campaign data only (no ad creative images or audience details)
• Data refresh depends on platform (Google: 4-6 hours, Meta: 1-3 hours behind)
• 20 requests per second per token (more than enough for normal use)

How Do I Keep My Connection Safe?

OAuth Stores No Key — Nothing to Leak

When you connect via OAuth (Claude, ChatGPT, Cursor, VS Code), there’s no key to copy, paste, or lose. You sign in, approve read-only access, and Flyweel — not your AI tool — holds the credential. To cut off a client, disconnect the Flyweel connector in the tool, or revoke it from Settings → API & MCP. This is why OAuth is the recommended path.

API Keys Are Secrets — Treat Them Like Passwords

If you use an API key for a headless or CLI client, the usual rules apply:

• Don’t share your key
• Don’t put it in emails or Slack
• Don’t commit it to Git or paste it into logs

Make a separate key per client and name it clearly (“Work Laptop - Claude Code”, “CI - nightly report”). If one leaks or a device is lost, deactivate or delete just that key — the others keep working.

Deactivate or Delete Keys You Don’t Use

Go to Settings → API & MCP. Toggle a key off to deactivate it, or click the trash icon to delete it. Deleting revokes access immediately.

Frequently Asked Questions

What is MCP?

MCP stands for Model Context Protocol. It’s a standard way for AI tools like Claude to connect to external apps and data. Think of it like a universal plug that lets your AI talk to other software.

What is Flyweel MCP used for?

Flyweel MCP lets you ask your AI questions about your Google Ads and Meta Ads campaigns. Instead of logging into dashboards and clicking around, you just ask in plain English and get answers with real data.

Which AI tools work with Flyweel MCP?

Flyweel MCP works with Claude (web & desktop), ChatGPT, Cursor, VS Code, Windsurf, Zed, and more. Any AI tool that supports MCP will work. Claude, ChatGPT, Cursor, and VS Code connect via OAuth (no API key needed).

Which ad platforms does Flyweel MCP support?

Flyweel MCP supports Google Ads, Meta Ads (Facebook and Instagram), and TikTok Ads (public release end of April 2026). That includes Search, Display, Shopping, PMAX, and YouTube on Google; Feed, Reels, and Stories on Meta; and In-Feed and Spark Ads on TikTok. Pipedrive CRM is also available for deal, pipeline, velocity, and win-rate questions.

Can Flyweel MCP change my campaigns?

No. Flyweel MCP is read-only. Your AI can view your ad data but cannot pause campaigns, change budgets, or edit anything. Your campaigns are completely safe.

Do I need an API key?

No — most people don’t. Claude, ChatGPT, Cursor, and VS Code connect over OAuth: you paste Flyweel’s server URL, sign in, and approve access. An API key is only for headless / CI use or CLI clients that can’t do OAuth.

How does OAuth keep my data safe?

You sign in to Flyweel and approve read-only access — no secret is ever stored in your AI tool. The connection is scoped to reading your ad data (it can’t change campaigns), and you can revoke it anytime from Settings → API & MCP or by disconnecting the connector in your AI tool. Because there’s no key to copy or paste, there’s nothing to leak.

What transport does Flyweel MCP use?

Streamable HTTP — the current remote-MCP standard. There’s a single server URL (https://api.flyweel.co/functions/v1/mcp-server/mcp); your client handles the rest.

How do I get my Flyweel API token?

Most clients don’t need one — connect via OAuth instead. If you need a key for a headless or CLI client, log in to app.flyweel.co, go to Settings → API & MCP, and under Advanced: use an API key instead click Generate API key (or Create Token to name your own). Copy the token immediately; you won’t see it again.

What does a Flyweel API key look like?

If you’re using the API-key fallback, your key starts with fwl_ followed by 64 characters — a long string of letters and numbers. Keep it private like a password. (OAuth connections don’t use a visible key.)

How long does setup take?

Most people finish setup in under 5 minutes. For OAuth clients you just paste Flyweel’s server URL and approve access — no config file or token to manage.

Is my data stored on Flyweel servers?

Yes. Flyweel syncs your ad data to provide fast responses. Your data is encrypted and stored securely. You control when to sync and can disconnect anytime.

Can I use multiple ad accounts?

Yes. You can connect multiple Google Ads and Meta Ads accounts to Flyweel. When asking questions, specify which account you want to know about.

Can I choose which accounts my AI looks at?

Yes. If you have multiple accounts, you can tell your AI which ones to include or exclude from your queries. Ask “Stop analyzing [account name]” to remove one, or “Add [account name] to my analysis” to include it again.

What if I have multiple devices?

Just connect each one via OAuth — each connection is independent, so there’s nothing to copy between devices. If you’re using API keys instead, create a separate key per device and name it clearly (“Work Laptop”, “Home Mac”); if you lose a device, delete just that key and the others keep working.

How do I revoke access?

For an OAuth connection, disconnect the Flyweel connector in your AI tool, or revoke it from Settings → API & MCP. For an API key, go to Settings → API & MCP and toggle it off to deactivate it, or click the trash icon to delete it. Access is cut off immediately.

Why isn’t my AI seeing Flyweel?

On OAuth clients, reopen the Flyweel connector and finish the sign-in and approve step. On API-key clients, check three things:

1. The config file is in the right folder (e.g., ~/.claude.json, ~/.cursor/mcp.json)
2. The file is valid JSON with the flyweel-mcp-server entry
3. Your JSON has no typos. Validate it at jsonlint.com.

Then restart your AI tool completely.

Why do I see “Authentication Error”?

If you’re using an API key, it’s wrong or has been deleted. Go to Flyweel → Settings → API & MCP and check the key exists and is active. If not, generate a new one and update your config file. If you connected via OAuth, disconnect and reconnect the Flyweel connector in your AI tool.

Why do I see “No accounts found”?

You haven’t connected your ad accounts to Flyweel yet. Go to Settings → Connections and link your Google Ads or Meta Ads accounts. Wait a minute for the first sync.

How do I get help?

Email team@flyweel.co for anything. We reply within 24 hours.

Troubleshooting

”Authentication Error” or “Invalid Token”

Your API key is wrong, inactive, or deleted.

Fix: Go to app.flyweel.co → Settings → API & MCP. Check the key is there and active. If not, generate a new one and update your config file. On OAuth clients, reconnect the Flyweel connector instead.

”No accounts found”

You haven’t connected your ad accounts to Flyweel yet.

Fix: Go to Settings → Connections in Flyweel. Connect your Google Ads or Meta Ads. Wait a minute for it to sync.

AI doesn’t see Flyweel

On OAuth clients, the connector didn’t finish connecting. On API-key clients, the config file is in the wrong spot or has a typo.

Fix (OAuth): Reopen the Flyweel connector in your AI tool and finish the sign-in and approve step, then restart the tool.

Fix (API key):

1. Check the file is named exactly right
2. Check it’s in the right folder:
   • Claude Code: ~/.claude.json
   • Cursor: ~/.cursor/mcp.json
   • VS Code: .vscode/mcp.json (rename the mcpServers key to servers)
   • Project-local: .mcp.json
3. Check for typos at jsonlint.com
4. Restart your AI tool fully (quit and reopen)

Data looks old

Fix: Go to your Flyweel dashboard. Click Sync Now on the account.

Quick Reference

Connection Details

Supported Platforms

Config File Locations (API-key clients only)

OAuth clients (Claude, ChatGPT, Cursor, VS Code) don’t need a config file.

Glossary

Request a Feature

Have an idea for a tool or feature? Let us know.

Get Help

Email team@flyweel.co for anything.

We reply within 24 hours.

Last updated: July 2026