linkedin-ads-mcp

MCP server for the LinkedIn Marketing API, with built-in MCC-style client switching across every ad account your LinkedIn login can access.

Installation

Once published to PyPI:

uv tool install linkedin-ads-mcp-py

This installs the linkedin-ads-mcp and linkedin-ads-auth commands. Or run it directly without installing:

uvx --from linkedin-ads-mcp-py linkedin-ads-mcp

Point your MCP client (e.g. .mcp.json or Claude Desktop's config) at the linkedin-ads-mcp command.

Setup

1. Create an app at LinkedIn Developers with access to the Advertising API product (requires LinkedIn's approval — see their docs, no published SLA).

2. Add http://localhost:3000/callback (or your own LINKEDIN_REDIRECT_URI) to the app's authorized redirect URLs.

3. Set the following environment variables (e.g. in a .env file in your working directory, or directly in your MCP client's server config):

   LINKEDIN_CLIENT_ID=your_client_id
   LINKEDIN_CLIENT_SECRET=your_client_secret
   # Optional overrides:
   # LINKEDIN_REDIRECT_URI=http://localhost:3000/callback
   # LINKEDIN_TOKEN_PATH=/path/to/tokens.json
   

4. Authenticate (opens a browser for the LinkedIn OAuth consent screen):

   uvx --from linkedin-ads-mcp-py linkedin-ads-auth
   

   Tokens are saved to ~/.linkedin-ads-mcp/tokens.json by default and refreshed automatically when a refresh token is available.

5. Run the server:

   uvx --from linkedin-ads-mcp-py linkedin-ads-mcp
   

Headless / remote deployments

Hosts that can't open a browser or receive the local OAuth callback (e.g. MCP Anywhere) can't run linkedin-ads-auth themselves. Instead, run it once locally as above, then read the refresh_token value out of the saved token file (~/.linkedin-ads-mcp/tokens.json by default) and set it as LINKEDIN_REFRESH_TOKEN alongside LINKEDIN_CLIENT_ID/LINKEDIN_CLIENT_SECRET in that host's environment variables. On first tool call, the server exchanges it for a live access token automatically, no browser needed at runtime.

MCC / multi-account support

Unlike the original TypeScript linkedin-ads-mcp, this server exposes every ad account your LinkedIn login can access and lets you switch between them by name or ID:

• list_clients — list all accessible ad accounts (call this first)
• set_active_client — select a default account (by name or numeric ID) for subsequent calls
• get_active_client — show which account is currently active

Every account-specific tool also accepts an optional account argument to target a client directly without changing the active selection.

Tools

Architecture

• auth/oauth.py — OAuth 2.0 authorization-code flow, browser + local callback server
• auth/token_store.py — persistent token storage with automatic refresh
• api/client.py — LinkedInClient, async wrapper around the LinkedIn Marketing REST API
• api/types.py — Pydantic models for API entities and responses
• context.py — ServerContext singleton holding the active client and name→ID cache
• tools/accounts.py — MCC tools (list_clients, set_active_client, get_active_client)
• server.py — MCP stdio server, tool registration

Development

uv sync
uv run pre-commit install

uv run ruff format
uv run ruff check
uv run mypy src/
uv run pytest

Building and publishing

uv build

Publishing to PyPI is handled by .github/workflows/pypi-publish.yml via PyPI trusted publishing whenever a GitHub release is published — no API token needed once the trusted publisher is configured on the PyPI project.

License

MIT License - see LICENSE file for details.