mcp-agencyanalytics-python

AgencyAnalytics MCP Server

A Python Model Context Protocol (MCP) server for AgencyAnalytics that enables AI assistants to manage campaigns, users, backlinks, keywords, and SEO rankings through natural language.

Works with: Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, Zed, and any MCP-compatible client.

Brought to you by Osher Digital - Specialist AI consultants helping businesses harness the power of artificial intelligence.

Features

• 21 Tools covering the full AgencyAnalytics API surface
• Campaign Management - Create, read, update, and delete campaigns (clients)
• User Management - Full CRUD for platform users with role and access control
• Backlink Tracking - Manage custom backlinks per campaign with domain/page authority
• SEO Rankings - Pull keyword-level and campaign-level ranking data across Google, Google Mobile, Google Places, and Bing
• Keyword Monitoring - Read tracked keywords per campaign
• Competitor Tracking - Add competitor URLs to campaigns for rank comparison
• SSO Login Grants - Generate one-time login tokens for client portal access
• Tag Management - Create organizational tags

Prerequisites

• Python 3.10+
• uv (recommended) or pip
• An AgencyAnalytics account on a Premier plan (API access required)
• An API key (Admin users only)

Getting Your API Key

1. Log in to AgencyAnalytics as an Admin user
2. Go to Admin Settings > Company Details
3. Your API key is at the bottom right of the page

Note: Only account Admin users can access the API key. API access is only available on Premier plans. The API key does not expire.

Installation

1. Clone the Repository

git clone https://github.com/osherai/mcp-agencyanalytics-python.git
cd mcp-agencyanalytics-python

2. Install Dependencies

Using uv (recommended):

uv venv && uv pip install -e .

Or using pip:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

3. Configure Credentials

Copy the example environment file and add your API key:

cp .env.example .env

Edit .env:

AGENCYANALYTICS_API_KEY=your_api_key_here

4. Test the Connection

uv run agencyanalytics-mcp

The server should start without errors (it will wait for input on stdin).

Client Configuration

This MCP server works with any MCP-compatible client. Below are setup instructions for popular clients.

Note: Replace /path/to/mcp-agencyanalytics-python with your actual installation path in all examples below.

---

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agencyanalytics": {
      "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
      "args": ["-m", "agencyanalytics_mcp.server"],
      "cwd": "/path/to/mcp-agencyanalytics-python"
    }
  }
}

Restart Claude Desktop (fully quit and reopen) for changes to take effect.

---

Claude Code (CLI)

Add the server using the Claude Code CLI:

claude mcp add agencyanalytics \
  -e AGENCYANALYTICS_API_KEY=your_api_key_here \
  -- /path/to/mcp-agencyanalytics-python/.venv/bin/python -m agencyanalytics_mcp.server

Or add to your ~/.claude/settings.json:

{
  "mcpServers": {
    "agencyanalytics": {
      "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
      "args": ["-m", "agencyanalytics_mcp.server"],
      "cwd": "/path/to/mcp-agencyanalytics-python"
    }
  }
}

---

Cursor

Add to your Cursor MCP configuration:

macOS: ~/.cursor/mcp.json Windows: %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "agencyanalytics": {
      "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
      "args": ["-m", "agencyanalytics_mcp.server"],
      "cwd": "/path/to/mcp-agencyanalytics-python"
    }
  }
}

Restart Cursor for changes to take effect.

---

Windsurf (Codeium)

Add to your Windsurf MCP configuration:

macOS: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "agencyanalytics": {
      "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
      "args": ["-m", "agencyanalytics_mcp.server"],
      "cwd": "/path/to/mcp-agencyanalytics-python"
    }
  }
}

Restart Windsurf for changes to take effect.

---

VS Code with Cline Extension

Add to your Cline MCP settings:

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "agencyanalytics": {
      "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
      "args": ["-m", "agencyanalytics_mcp.server"],
      "cwd": "/path/to/mcp-agencyanalytics-python"
    }
  }
}

---

VS Code with Continue Extension

Add to your Continue configuration at ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
          "args": ["-m", "agencyanalytics_mcp.server"],
          "cwd": "/path/to/mcp-agencyanalytics-python"
        }
      }
    ]
  }
}

---

Zed Editor

Add to your Zed settings at ~/.config/zed/settings.json:

{
  "context_servers": {
    "agencyanalytics": {
      "command": {
        "path": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
        "args": ["-m", "agencyanalytics_mcp.server"]
      },
      "settings": {}
    }
  }
}

---

Example Queries

Once configured, you can ask natural language questions about your AgencyAnalytics data:

• "List all my campaigns"
• "Show me the keyword rankings for campaign 123"
• "Create a new client user for jane@acme.com"
• "What backlinks do we have for the Acme Corp campaign?"
• "Generate an SSO login link for user 456"
• "Add competitor example.com to campaign 123"

Tools Reference

Campaign Tools

Campaigns are called "Clients" in the AgencyAnalytics UI (renamed February 2025), but the API still uses the term "campaign".

list_campaigns

List campaigns with pagination.

Parameter	Type	Required	Default	Description
offset	integer	No	0	Pagination offset
limit	integer	No	50	Max results per page

get_campaign

Get a single campaign by ID.

Parameter	Type	Required	Description
campaign_id	integer	Yes	The campaign ID

create_campaign

Create a new campaign.

Parameter	Type	Required	Description
url	string	Yes	Website URL for the campaign
company	string	Yes	Company/client name

update_campaign

Update an existing campaign.

Parameter	Type	Required	Description
campaign_id	integer	Yes	The campaign ID to update
url	string	No	New website URL
company	string	No	New company name

delete_campaign

Delete a campaign by ID.

Parameter	Type	Required	Description
campaign_id	integer	Yes	The campaign ID to delete

---

User Tools

list_users

List all platform users with pagination.

Parameter	Type	Required	Default	Description
offset	integer	No	0	Pagination offset
limit	integer	No	50	Max results per page

Returned fields: id, date_created, date_modified, email, username, first_name, last_name, role, campaign_access, status, account_id, campaign_id

get_user

Get a single user by ID.

Parameter	Type	Required	Description
user_id	integer	Yes	The user ID

create_user

Create a new user.

Parameter	Type	Required	Default	Description
email	string	Yes	-	User email address
first_name	string	Yes	-	First name
last_name	string	Yes	-	Last name
role	string	No	client	User role
campaign_access	string	No	restricted	restricted or all
campaign_id	integer	No	-	Campaign to grant access to

update_user

Update an existing user.

Parameter	Type	Required	Description
user_id	integer	Yes	The user ID to update
email	string	No	New email
first_name	string	No	New first name
last_name	string	No	New last name
role	string	No	New role
campaign_access	string	No	New access level

delete_user

Delete a user by ID.

Parameter	Type	Required	Description
user_id	integer	Yes	The user ID to delete

---

Backlink Tools

list_backlinks

List backlinks with optional campaign filtering.

Parameter	Type	Required	Default	Description
campaign_id	integer	No	-	Filter by campaign
offset	integer	No	0	Pagination offset
limit	integer	No	50	Max results per page

Returned fields: id, title, status, date_created, date_published, url, link_type, target_anchor, target_url, notes, campaign_id, domain_authority, page_authority

create_backlink

Create a new backlink.

Parameter	Type	Required	Description
campaign_id	integer	Yes	Campaign to associate with
title	string	Yes	Backlink title
url	string	Yes	Page URL where link appears
target_url	string	Yes	URL the link points to
target_anchor	string	No	Anchor text
link_type	string	No	Type of link
status	string	No	Backlink status
notes	string	No	Additional notes

update_backlink

Update an existing backlink.

Parameter	Type	Required	Description
backlink_id	integer	Yes	The backlink ID to update
title	string	No	New title
url	string	No	New page URL
target_url	string	No	New target URL
target_anchor	string	No	New anchor text
status	string	No	New status
notes	string	No	New notes

delete_backlink

Delete a backlink by ID.

Parameter	Type	Required	Description
backlink_id	integer	Yes	The backlink ID to delete

---

Keyword & Ranking Tools

list_keywords

List tracked keywords for a campaign. Keywords can only be queried one campaign at a time.

Parameter	Type	Required	Default	Description
campaign_id	integer	Yes	-	The campaign ID
offset	integer	No	0	Pagination offset
limit	integer	No	50	Max results per page

get_keyword_rankings

Get keyword-level ranking data for a campaign. Returns positions across Google, Google Mobile, Google Places, and Bing with change tracking, SERP URLs, and monthly search volume.

Parameter	Type	Required	Default	Description
campaign_id	integer	Yes	-	The campaign ID
offset	integer	No	0	Pagination offset
limit	integer	No	50	Max results per page

Returned fields include: keywordId, keywordPhrase, googleRanking, googleRankingChange, googleRankingUrl, googleMobileRanking, googleMobileRankingChange, googlePlacesRanking, bingRanking, bingRankingChange, localMonthlySearches, and more.

get_campaign_rankings

Get aggregate campaign ranking data over time. Returns historical trends with ranking distribution (positions 1-3, 4-10, 11-20, 21-50, 51+) and competitor data.

Parameter	Type	Required	Default	Description
campaign_id	integer	Yes	-	The campaign ID
offset	integer	No	0	Pagination offset
limit	integer	No	50	Max results per page

---

Other Tools

create_competitor

Add a competitor URL to a campaign for rank comparison.

Parameter	Type	Required	Description
campaign_id	integer	Yes	Campaign to add competitor to
url	string	Yes	Competitor website URL

create_tag

Create an organizational tag.

Parameter	Type	Required	Description
name	string	Yes	Tag name

create_login_grant

Generate a one-time SSO login URL for a user. The token allows logging into AgencyAnalytics without a password. Useful for embedding reports or building custom login pages.

Parameter	Type	Required	Description
user_id	integer	Yes	User to generate login token for

Returns: token, login_url, time, user_id, origin_user_id

Architecture

How the AgencyAnalytics API Works

Unlike traditional REST APIs, the AgencyAnalytics API uses a single POST endpoint (https://apirequest.app/query) for all operations. Every request includes a JSON body specifying:

• provider - Always "agency-analytics-v2"
• asset - The resource type (campaign, user, backlink, keyword, etc.)
• operation - The action (create, read, update, delete)
• fields - Which fields to return (for read operations)
• rows - Data for create/update/delete operations
• offset / limit - Pagination

Authentication uses HTTP Basic Auth with an empty username and your API key as the password.

API Assets and Supported Operations

Asset	Create	Read	Update	Delete	Notes
campaign	Yes	Yes	Yes	Yes	Called "Client" in UI since Feb 2025
user	Yes	Yes	Yes	Yes	Platform users with roles
backlink	Yes	Yes	Yes	Yes	Custom backlink tracking
keyword	-	Yes	-	-	Read only; requires campaign_id
keyword-rankings	-	Yes	-	-	Read only; ranking feed data
campaign-rankings	-	Yes	-	-	Read only; aggregate ranking feed
competitor	Yes	-	-	-	Create only
tag	Yes	-	-	-	Create only
login-grant	Yes	-	-	-	Create only; SSO tokens

API Limitations

The AgencyAnalytics API is designed for platform management and SEO data retrieval. It does not provide access to:

• Third-party integration data (Google Ads, Facebook Ads, GA4, social media, etc.)
• Report generation or export
• Dashboard/widget data
• PPC, email marketing, or eCommerce metrics

While AgencyAnalytics connects to 90+ integrations in its UI, none of that data is exposed through the API.

Request Lifecycle

MCP Tool Call
  -> AgencyAnalyticsClient._build_payload()  (construct JSON body)
  -> AgencyAnalyticsClient._request()         (POST to https://apirequest.app/query)
  -> Parse response { metadata, data }
  -> format_response()                        (JSON with summary)
  -> Return to MCP client

Project Structure

mcp-agencyanalytics-python/
├── pyproject.toml                  # Project config, dependencies, entry point
├── .env.example                    # Environment variables template
├── .gitignore                      # Python/IDE/OS ignores
├── README.md                       # This file
├── src/
│   └── agencyanalytics_mcp/
│       ├── __init__.py             # Package version
│       ├── server.py               # MCP server with 21 tool definitions
│       ├── config.py               # Dataclass config loaded from environment
│       └── client.py               # AgencyAnalytics API client wrapper
└── tests/
    ├── __init__.py
    ├── conftest.py                 # Shared pytest fixtures
    ├── test_config.py              # Configuration tests
    ├── test_client.py              # API client tests
    └── test_server.py              # MCP tool tests

Key Design Decisions

• Lazy client initialization - The API client is created on first use and cached globally, avoiding unnecessary auth on startup
• Synchronous HTTP - Uses httpx.Client (sync) since the AgencyAnalytics API is a single endpoint with no parallelism benefit
• Error strings - Tools return "ERROR: ..." strings rather than raising exceptions, following MCP conventions for graceful error handling
• JSON responses - All tool responses use json.dumps(data, indent=2, default=str) for consistent, readable output

Environment Variables

Variable	Required	Default	Description
AGENCYANALYTICS_API_KEY	Yes	-	Your AgencyAnalytics API key (Admin Settings > Company Details)
AGENCYANALYTICS_BASE_URL	No	https://apirequest.app/query	API endpoint URL (override for testing)

Testing

Running Tests

# Install dev dependencies
uv pip install -e ".[dev]"

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run a specific test file
uv run pytest tests/test_client.py

# Run a specific test class
uv run pytest tests/test_server.py::TestListCampaigns

Test Structure

tests/
├── conftest.py         # Fixtures: sample_config, sample_campaign, sample_user,
│                       #   sample_backlink, sample_keyword_ranking, sample_api_response
├── test_config.py      # Tests for environment loading and validation (5 tests)
├── test_client.py      # Tests for auth headers, payload building, HTTP requests,
│                       #   and client methods (15 tests)
└── test_server.py      # Tests for each MCP tool with mocked client (14 tests)

All tests use unittest.mock to mock the API client. No real API calls are made during testing.

Troubleshooting

"Missing required environment variable: AGENCYANALYTICS_API_KEY"

Ensure your .env file exists in the project root and contains your API key:

AGENCYANALYTICS_API_KEY=your_api_key_here

"Authentication failed. Check your API key."

1. Verify your API key is correct (Admin Settings > Company Details)
2. Confirm your account is on a Premier plan with API access
3. Ensure you are an Admin user

"API error" responses

The AgencyAnalytics API may return errors for:

• Invalid asset names or operations
• Missing required fields in create/update operations
• Invalid filter values (e.g., non-existent campaign IDs)
• Rate limiting (specific limits are not publicly disclosed)

MCP server not appearing in your client

1. Ensure the config file path is correct for your client (see Client Configuration section)
2. Verify the Python path in the config points to the .venv directory
3. Fully quit and restart your client application
4. Check your client's logs for error messages
5. Test the server manually:

   cd /path/to/mcp-agencyanalytics-python
   .venv/bin/python -m agencyanalytics_mcp.server
   

   The server should start without errors (it will wait for input on stdin)

Keywords returning empty results

Keywords can only be queried one campaign at a time. You must provide a campaign_id:

list_keywords(campaign_id=123)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• AgencyAnalytics for their API
• Model Context Protocol for the MCP specification
• Anthropic for Claude and the MCP Python SDK
• The teams behind Cursor, Windsurf, Cline, Continue, and Zed for MCP support

---

About Osher Digital

This project is maintained by Osher Digital, specialist AI consultants based in Australia. We help businesses integrate AI solutions to streamline operations and drive growth.

Need help with AI integration? Get in touch

Disclaimer

This is an unofficial, community-maintained project. It is not affiliated with, officially maintained, or endorsed by AgencyAnalytics.