flin-microsoft-ads-mcp
Read-only Microsoft Advertising REST API v13 reporting and account discovery for Claude Desktop, with OAuth sign-in and connection/auth diagnostics.
Inspect configured/running versions and optionally test live account discovery.
Check local sign-in state, start browser OAuth, or clear the saved refresh token/pending sign-in.
List accessible advertising accounts with pagination, including account Id and ParentCustomerId.
Retrieve campaigns, ad groups, ads, and keywords for supported campaign/ad types.
Get performance insights for account, campaign, ad group, ad, keyword, or search-term levels over inclusive ISO date ranges up to 367 days, optionally daily and with selectable timezones.
Query metrics such as clicks, impressions, spend, conversions, and revenue. No campaign mutation, arbitrary API execution, bulk download, or billing tools are exposed.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@flin-microsoft-ads-mcp Show campaign spend, clicks, and conversions for Nov 1–7, 2026."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
flin-microsoft-ads-mcp
Read-only Microsoft Advertising REST API v13 reporting in Claude Desktop. Built with Microsoft's official msads Python SDK, MCPServer and the same UV/MCPB setup as flin Google Ads MCP.
Setup
You need two values before connecting: a production developer token from Microsoft Advertising and an application (client) ID from Microsoft Entra. Follow the steps below to obtain both.
1. Get a production developer token
Open Microsoft Advertising → Developer settings. This is the current portal; it replaces the old Developer Portal linked in older guides.
Sign in with a Microsoft Advertising user that has the Super Admin role. A Microsoft Advertising account is required; if you do not have one, create it first.
Select the user to associate with the token, then click Request Token and complete any requested information. If a universal developer token is already available, use that token.
Copy the token for the extension's Developer token field in step 3 below. For manual configuration, the corresponding environment variable is
MICROSOFT_ADS_DEVELOPER_TOKEN.
One universal developer token can be used across multiple users and client accounts. It does not grant access to additional advertising accounts: the user who signs in during step 4 must already have access to the accounts you want to query. This server requires a production token; the shared sandbox token will not work.
If you cannot request a token, first check that you are signed in with the correct Microsoft Advertising user and have the Super Admin role. See Microsoft's developer token instructions for details.
2. Register the sign-in application
Open Microsoft Entra app registrations and register your own application.
Select Accounts in any organizational directory and personal Microsoft accounts.
Copy the Application (client) ID for the extension's OAuth client ID field.
Under Authentication, add the Mobile and desktop applications platform and redirect URI
http://localhost/.
This public-client authorization-code flow uses PKCE; no client secret is needed. Do not register it as a Web application. If your organization restricts app consent, ask its administrator to approve the application.
3. Install and configure the extension
In Claude Desktop, open Settings → Extensions → Advanced settings → Install Extension… and select the downloaded file. Requires a Claude version supporting the MCPB UV runtime.
Enter the two values in the extension settings:
Extension setting | Value |
Developer token | Production developer token from Microsoft Advertising (step 1) |
OAuth client ID | Application (client) ID from Microsoft Entra (step 2) |
Enter credentials in settings, never in chat. Leave Refresh token, Default account ID and Default customer ID empty for the initial setup; they are optional.
4. Sign in to Microsoft Advertising
Enable the extension and ask Claude to run
get_auth_url.Open the returned Microsoft URL on the same computer, sign in with a Microsoft user who has access to the advertising accounts, and grant Microsoft Advertising access.
Keep Claude running until the browser confirms completion. Tokens are saved automatically; do not copy tokens or callback URLs into chat.
5. Check the connection and select an account
Ask Claude to run
connection_status(check_live=true), thenlist_accounts.Use Id as
account_idand ParentCustomerId ascustomer_id. These are numeric API IDs, not the account number. You can now save them as optional defaults in the extension settings.Ask for campaigns or a report, for example: «Show campaign spend, clicks and conversions from 2026-11-01 to 2026-11-07 for account ID … and customer ID …».
The extension is macOS-targeted (Apple Silicon and Intel). The Python stdio server can also be configured manually on Windows/Linux. Internet is required at startup; the new extension resolves stable >=0.1.1,<0.2 releases. Existing 0.1.0 extensions also accept 0.1.1 updates. Updates apply after restart, while local tokens persist. Python 3.12 is selected by the extension runtime.
Related MCP server: Microsoft Advertising MCP Connector
Updates and versions
The installed MCPB checks PyPI whenever Claude starts its MCP process. It installs the latest stable 0.1.x server available there, including bug fixes, before starting. To load an update, fully quit Claude Desktop (Cmd+Q) and reopen it. An existing session keeps its current version. Local code changes or a GitHub push alone do not update an installed extension; the new server must be published on PyPI first.
Run connection_status(check_live=false) to see the actual server_version, api_transport, microsoft_sdk_version and mcp_sdk_version. These are the running versions; Claude's extension listing can still show the version of the originally installed MCPB. Saved sign-in tokens remain available after an update.
A new MCPB is needed for launcher/settings changes or to move beyond the configured <0.2 server range. Ordinary server updates within 0.1.x do not require reinstalling the extension.
Verified package versions on 2026-11-14:
Component | Version / transport |
Microsoft Advertising API | v13, REST/JSON |
Microsoft Python SDK |
|
MCP Python SDK |
|
Requests | 2.34.2 |
Pydantic | 2.14.3 |
uv.lock records the exact tested dependencies. Microsoft recommends migrating to REST before SOAP is retired on January 31, 2027. The msads package still uses the Python import namespace bingads; do not install the legacy bingads package alongside it.
Tools
Tool | Purpose |
| Local configuration/version; optional live check |
| Local authentication and browser sign-in state |
| Start browser OAuth; localhost callback expires after 10 minutes |
| Delete local token and cancel pending sign-in |
| Accessible accounts, paginated using |
| Search, Shopping, Dynamic Search, Audience and Performance Max campaigns |
| Ad groups in a campaign |
| Supported ad types and their creative fields |
| Configured keywords in an ad group |
| Account, campaign, ad group, ad, keyword or actual search-term performance |
Reports require inclusive ISO dates (YYYY-MM-DD), up to 367 days per request; daily=true adds daily rows. Default report timezone is AmsterdamBerlinBernRomeStockholmVienna (Swiss local time, including daylight saving). UK and Pacific timezones are also exposed. Metrics retain Microsoft CSV strings; unavailable values are not zero. Spend/revenue use account currency, not micros. Report downloads can take two minutes; SDK authentication can add up to five minutes if Microsoft is unresponsive. Recent data may be incomplete; search queries can be withheld by Microsoft. truncated=true means the output limit was reached; narrow dates/scope or increase limit (maximum 1,000). Entity limits cap returned data, not the upstream download. No campaign mutation, arbitrary API execution, bulk download or billing tools are exposed.
Manual Claude configuration
For a manual installation, add to claude_desktop_config.json (merge with existing servers):
{
"mcpServers": {
"flin-microsoft-ads-mcp": {
"command": "uvx",
"args": ["--prerelease", "disallow", "--upgrade-package", "flin-microsoft-ads-mcp", "--from", "flin-microsoft-ads-mcp>=0.1.1,<0.2", "flin-microsoft-ads-mcp"],
"env": {
"MICROSOFT_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
"MICROSOFT_ADS_CLIENT_ID": "YOUR_APPLICATION_CLIENT_ID"
}
}
}
}Use an absolute path to uvx if Claude cannot find it. On macOS the config is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows %APPDATA%\Claude\claude_desktop_config.json.
For source checkout, use command uv, args ["run", "--directory", "/absolute/path/to/flin-microsoft-ads-mcp", "flin-microsoft-ads-mcp"] and the same environment.
Optional environment settings:
MICROSOFT_ADS_ACCOUNT_ID,MICROSOFT_ADS_CUSTOMER_ID: default API IDs.MICROSOFT_ADS_AUTH_FILE: defaults to~/.config/flin-microsoft-ads-mcp/auth.json.MICROSOFT_ADS_REFRESH_TOKEN: optional bootstrap token; saved/rotated token takes precedence. Remove it before signing out permanently.MICROSOFT_ADS_OAUTH_REDIRECT_URI: optionalhttp://localhost:PORT/; defaults to a temporary available port. Registerhttp://localhost/in Entra.
Production Microsoft accounts are supported. No sandbox or Google-identity sign-in is implemented. No .env file is loaded automatically: set process environment variables or use Claude settings.
Development and release
uv sync --extra dev
uv run pytest
uv run python scripts/check_api_schema.py # REST model/JSON checks, no credentials
uv build
uv run python scripts/build_mcpb.py
uv run python scripts/smoke_mcpb.py dist/flin-microsoft-ads-mcp.mcpb --wheel dist/flin_microsoft_ads_mcp-0.1.1-py3-none-any.whl --expected-version 0.1.1CI tests Python 3.11–3.14, validates the REST models, builds distributions and validates the MCPB manifest. Releases on v* tags test/build, publish via PyPI Trusted Publishing, smoke-test the published package and attach MCPB/wheel/sdist to GitHub Releases.
PyPI trusted publisher: project flin-microsoft-ads-mcp, owner flin-agency, repository flin-microsoft-ads-mcp, workflow release.yml, environment pypi (an unrestricted publisher also matches). No PyPI token secret is needed. To release: match project/manifest/desktop/server versions, commit, tag v0.1.1 and push the tag.
See testing, desktop setup, privacy, security, and support.
API references
Available Tools
10 toolsauth_statusBRead-only
Return local sign-in status, without tokens.
Inputs: no named parameters.
clear_auth_tokenADestructive
Delete the local refresh token and cancel pending sign-in. Does not revoke Microsoft consent.
Inputs: no named parameters.
connection_statusCRead-only
Inspect setup without exposing secrets; optionally test live account discovery.
Inputs: check_live.
get_ad_groupsCRead-only
Get ad groups for a campaign.
Inputs: campaign_id (required), limit, account_id, customer_id.
get_adsCRead-only
Get responsive search, responsive, expanded text, dynamic search and product ads.
Inputs: ad_group_id (required), limit, account_id, customer_id.
get_auth_urlA
Start browser sign-in on this computer. Open URL; token is saved automatically.
Inputs: no named parameters.
get_campaignsBRead-only
Get campaigns across supported campaign types; IDs can default from configuration.
Inputs: limit, account_id, customer_id.
get_insightsBRead-only
Performance report for inclusive YYYY-MM-DD dates (up to 367 days). Includes clicks, impressions, spend, conversions and revenue. Can take up to two minutes; recent data may be incomplete. Search terms may be limited by Microsoft's privacy rules.
Inputs: end_date (required), start_date (required), daily, level, +4 more.
get_keywordsBRead-only
Get configured keywords; use search_term insights for actual search queries.
Inputs: ad_group_id (required), limit, account_id, customer_id.
list_accountsBRead-only
Discover accessible accounts, including account Id and ParentCustomerId. Follow next_page_index.
Inputs: page_size, page_index.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
The tools are mostly clearly separable: auth and connection status tools cover setup versus local sign-in, while the read tools map cleanly to accounts, campaigns, ad groups, ads, keywords, and insights. There is minor overlap between connection_status and auth_status, but descriptions make the boundary workable.
All tool names use snake_case and most follow a verb_noun pattern such as get_campaigns, list_accounts, and clear_auth_token. The status tools use noun_status naming, which is a minor deviation but still readable and predictable.
Ten tools is well scoped for an authentication plus reporting MCP server. Each tool appears to earn its place without obvious filler or missing adjacent helper operations.
The set covers the auth lifecycle, account discovery, the campaign hierarchy, keywords, and performance insights. However, for a Microsoft Ads server it exposes only read/reporting operations and lacks create/update/delete or budget/targeting management, which is a notable lifecycle gap.
Maintenance
Related MCP Connectors
Conversational access to advertising performance data, creative analysis, and campaign insights
Conversational access to advertising performance data, creative analysis, and campaign insights
Open-source ad agent for LinkedIn Ads and Google Ads. Drafts campaigns, audiences and reports.
Manage Google Ads from ChatGPT, Claude or any MCP client. Sign in with OAuth or use an API key.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables AI assistants to manage Microsoft Advertising accounts, including campaigns, ad groups, keywords, audiences, and reporting, with safety-first write controls such as opt-in mutations, draft-and-confirm workflows, spend ceilings, and audit logging.471MIT
- FlicenseNot gradedqualityCmaintenanceEnables Claude.ai users to connect multiple Microsoft Advertising accounts and securely query customers, accounts, campaigns, ad groups, ads, keywords, and performance reports through MCP.-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query campaign performance, metrics, audiences, and geography, and to analyze budgets, wasted spend, and account health through natural language.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables managing and analyzing ad accounts in plain language from AI assistants, including cross-account performance reports, keyword research, GAQL queries, and safe previewed changes.MIT