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.