linkedin-ads-mcp-py 0.1.0__tar.gz

linkedin_ads_mcp_py-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: linkedin-ads-mcp-py
+Version: 0.1.0
+Summary: LinkedIn Ads MCP server with MCC client-switching support
+Keywords: mcp,ai,tools,linkedin,ads
+Author: LOCOMOTIVE Agency
+Author-email: LOCOMOTIVE Agency <erick@locomotive.agency>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# 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:
+
+```bash
+uv tool install linkedin-ads-mcp-py
+```
+
+This installs the `linkedin-ads-mcp` and `linkedin-ads-auth` commands. Or run it directly without
+installing:
+
+```bash
+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](https://www.linkedin.com/developers/apps) 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):
+
+   ```bash
+   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):
+
+   ```bash
+   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:
+
+   ```bash
+   uvx --from linkedin-ads-mcp-py linkedin-ads-mcp
+   ```
+
+## 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
+
+| Tool | Notes |
+|---|---|
+| `list_clients` | MCC view — call first |
+| `set_active_client` | select account by name or ID |
+| `get_active_client` | show current selection |
+| `get_account_details` | account metadata |
+| `list_campaign_groups` | |
+| `list_campaigns` | |
+| `get_campaign_performance` | report |
+| `get_campaign_groups_performance` | report |
+| `get_creative_performance` | report |
+| `get_audience_demographics` | report |
+| `get_audience_reach` | reach / frequency |
+| `compare_performance` | compare two time windows or entity sets |
+| `get_daily_trends` | daily time series |
+| `list_creatives` | |
+| `get_conversion_performance` | report |
+| `list_conversions` | |
+| `get_lead_gen_performance` | report |
+| `list_lead_forms` | |
+| `list_saved_audiences` | |
+
+## 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
+
+```bash
+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
+
+```bash
+uv build
+```
+
+Publishing to PyPI is handled by `.github/workflows/pypi-publish.yml` via
+[PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) 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.

linkedin_ads_mcp_py-0.1.0/README.md

@@ -0,0 +1,127 @@
+# 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:
+
+```bash
+uv tool install linkedin-ads-mcp-py
+```
+
+This installs the `linkedin-ads-mcp` and `linkedin-ads-auth` commands. Or run it directly without
+installing:
+
+```bash
+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](https://www.linkedin.com/developers/apps) 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):
+
+   ```bash
+   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):
+
+   ```bash
+   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:
+
+   ```bash
+   uvx --from linkedin-ads-mcp-py linkedin-ads-mcp
+   ```
+
+## 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
+
+| Tool | Notes |
+|---|---|
+| `list_clients` | MCC view — call first |
+| `set_active_client` | select account by name or ID |
+| `get_active_client` | show current selection |
+| `get_account_details` | account metadata |
+| `list_campaign_groups` | |
+| `list_campaigns` | |
+| `get_campaign_performance` | report |
+| `get_campaign_groups_performance` | report |
+| `get_creative_performance` | report |
+| `get_audience_demographics` | report |
+| `get_audience_reach` | reach / frequency |
+| `compare_performance` | compare two time windows or entity sets |
+| `get_daily_trends` | daily time series |
+| `list_creatives` | |
+| `get_conversion_performance` | report |
+| `list_conversions` | |
+| `get_lead_gen_performance` | report |
+| `list_lead_forms` | |
+| `list_saved_audiences` | |
+
+## 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
+
+```bash
+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
+
+```bash
+uv build
+```
+
+Publishing to PyPI is handled by `.github/workflows/pypi-publish.yml` via
+[PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) 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.

linkedin_ads_mcp_py-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "linkedin-ads-mcp-py"
+version = "0.1.0"
+description = "LinkedIn Ads MCP server with MCC client-switching support"
+authors = [{ name = "LOCOMOTIVE Agency", email = "erick@locomotive.agency" }]
+license = "MIT"
+readme = "README.md"
+keywords = ["mcp", "ai", "tools", "linkedin", "ads"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">= 3.12"
+dependencies = [
+    "fastmcp>=0.1.0",
+    "httpx>=0.27.0",
+    "loguru>=0.7.3",
+    "pydantic>=2.11.7",
+    "pydantic-settings>=2.10.1",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.15.0",
+    "pre-commit>=4.1.0",
+    "pytest>=8.3.4",
+    "pytest-asyncio>=0.25.3",
+    "ruff>=0.9.7",
+]
+
+[project.scripts]
+linkedin-ads-mcp  = "linkedin_ads_mcp.server:main"
+linkedin-ads-auth = "linkedin_ads_mcp.auth.oauth:main"
+
+[tool.uv.build-backend]
+module-name = "linkedin_ads_mcp"
+
+[build-system]
+requires = ["uv_build>=0.8.11,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 88
+src = ["src"]
+output-format = "concise"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "N", "ANN", "TRY", "PD", "RUF200", "UP", "G"]
+ignore = ["E501", "ANN003", "ANN401", "TRY003", "TRY301", "TRY300"]
+
+[tool.ruff.lint.extend-per-file-ignores]
+"__init__.py" = ["F401", "F403", "E402"]
+"tests/**/*.py" = ["D", "ANN"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 6
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

linkedin_ads_mcp_py-0.1.0/src/linkedin_ads_mcp/__init__.py

@@ -0,0 +1 @@
+"""LinkedIn Ads MCP server with MCC client-switching support."""

linkedin_ads_mcp_py-0.1.0/src/linkedin_ads_mcp/api/__init__.py

@@ -0,0 +1 @@
+"""LinkedIn Marketing API client and type definitions."""