# Marchex MCP > Marchex MCP Server connects your AI client to Marchex's conversation intelligence platform. Use it to search call records, analyze performance metrics, and manage campaign data. Your agent can list accounts, find specific calls using `search_calls`, retrieve granular call details via `get_call_details`, and calculate overall campaign health with `get_call_analytics`. ## Overview - **Category:** communication-messaging - **Price:** Free - **Tags:** call-tracking, conversation-intelligence, lead-attribution, telephony-analytics, campaign-performance ## Description Marchex MCP Server gives your AI client full control over conversation intelligence. You can analyze call outcomes and track marketing performance by having your agent interact directly with Marchex's data using specific tools. **Searching and Retrieving Call Records** Your agent uses `search_calls` to pull through entire call histories, letting you narrow down records based on criteria like date ranges or phone numbers. Once you find a potentially relevant record, it fetches all available metadata for that single call via `get_call_details`. This pair of tools lets your client drill deep into specific conversations and get the full picture of what happened. **Analyzing Campaign Performance** To understand how campaigns are doing, your agent first runs through all active and inactive tracking campaign setups by calling `list_campaigns`. If you need to know exactly how a particular campaign is configured or if its status changed, it uses `get_campaign_details` for that specific setup. For the big picture, `get_call_analytics` calculates and returns aggregated call performance metrics across any given time period, giving you an overall view of campaign health. **Managing Phone Numbers and Accounts** Your client handles everything related to infrastructure management. It starts by listing every phone number that can be used for tracking calls using `list_numbers`. When you need specific operational details on one of those numbers—like its current status or associated metadata—it pulls that info with `get_number_details`. For the user side, your agent can generate a simple listing of all users associated with the platform via `list_users`, and it also has access to `list_accounts` to return a list of every user account linked to Marchex. When you need deep insight into an individual organization or user's details, it runs `get_account_details`. **Putting It All Together** Your agent handles the entire lifecycle flow. You can check campaign setups with `get_campaign_details` and then use that context to run broad performance reports using `get_call_analytics`. The system maintains a clear separation between user management (`list_users`, `list_accounts`) and number/system management (`list_numbers`, `get_number_details`). Your AI client doesn't require you to jump through multiple dashboards; it just takes your natural language request—like, “What were the metrics for Q3?” or “Find me all calls from last Friday using this number”—and executes the precise sequence of tool calls needed to get the data. It’s direct. It’s immediate. ## Tools ### get_account_details Retrieves detailed information for a single specified user or organizational account. ### get_call_analytics Calculates and returns aggregated call performance metrics across a given time period. ### get_call_details Fetches all available metadata for one specific, identified phone call record. ### get_campaign_details Retrieves the full configuration and status details for a single tracking campaign. ### get_number_details Gets specific operational information about one registered phone number. ### list_accounts Returns a list of all user accounts associated with the Marchex system. ### list_campaigns Lists every active and inactive tracking campaign setup in your account. ### list_numbers Returns a list of all phone numbers that can be used for tracking calls. ### list_users Generates a simple listing of all user accounts associated with the platform. ### search_calls Searches through your entire call history using criteria like date range or phone number to find relevant records. ## Prompt Examples **Prompt:** ``` Search for calls from last week. ``` **Response:** ``` Fetching call records... I found 15 calls. Notable entries include calls from +1234567890 with durations around 2 minutes. ``` **Prompt:** ``` List active tracking campaigns. ``` **Response:** ``` Querying campaigns... You have 3 active campaigns: 'Spring Sale', 'Google Ads', and 'Facebook Ads'. ``` **Prompt:** ``` Show call analytics for today. ``` **Response:** ``` Calculating analytics... Today you had 50 total calls with an average duration of 3m 45s. ``` ## Capabilities ### Search & Retrieve Call Records Find specific call instances using timeframes or phone numbers with `search_calls`, then fetch complete metadata on any single call via `get_call_details`. ### Analyze Campaign Performance List all active campaigns (`list_campaigns`) and run deep analyses to get aggregated performance metrics using `get_call_analytics`. ### Manage Phone Numbers & Accounts See what numbers are available with `list_numbers`, check specific account details with `get_account_details`, or list all user accounts with `list_accounts`. ### Inspect Campaign Configuration View the setup and configuration of any tracking campaign using `get_campaign_details`. ### List Users and Numbers Get a list of all registered users (`list_users`) or check details on specific tracking phone numbers with `get_number_details`. ## Use Cases ### Investigating a Failed Campaign Launch The Marketing Manager notices 'Q3 Lead Gen' campaign calls are dropping. They ask the agent to run `list_campaigns` first, confirming the ID. Then, they instruct it to use `get_campaign_details` and finally run `search_calls` for that campaign's period to find the pattern: all failed calls originated from a specific number listed via `list_numbers`. The root cause is found in minutes. ### Auditing User Access and Performance The Support Lead needs to know if a certain employee (found using `get_account_details`) was responsible for all calls logged last month. They ask the agent to use `list_users` to confirm IDs, then run `search_calls` filtered by that user's timeframe and cross-reference call results with overall metrics from `get_call_analytics`. ### Determining Call Failure Source A customer reports a bad experience. The agent uses the phone number provided to run `get_number_details`. They then use that number in `search_calls`, and finally feed those results into `get_call_details` to pull up the exact call transcript metadata, solving the issue without needing CRM access. ### Comparing Campaign Structures A junior analyst needs to know why Campaign A performs better than Campaign B. Instead of looking at two dashboards, they ask the agent to run `get_campaign_details` for both campaigns sequentially and compare key fields like landing page URL or tracking method. ## Benefits - Pinpoint failure points fast. Instead of checking dashboards, ask your agent to run `search_calls` for a date range and immediately narrow it down with specific criteria like an incomplete conversation or duration under 30 seconds. - Understand campaign health in real-time. Use `get_call_analytics` to see total call counts and average duration without writing complex SQL queries, just by asking your agent. - Diagnose setup issues instantly. If a number isn't working, don't guess; run `get_number_details` to pull the current status and configuration of that specific tracking line. - Audit who did what. Use `list_users` and `get_account_details` when you need to confirm which user or account was responsible for a set of actions or data access. - Compare campaign performance easily. Run `list_campaigns`, then use `get_campaign_details` on the suspects, letting your agent compare their settings side-by-side in a single chat window. ## How It Works The bottom line is that you use natural conversation; the server handles all the API calls and data structuring. 1. Subscribe to the server and provide your Marchex Client ID and Secret. 2. Connect your preferred AI client (Claude, Cursor, etc.) to the Vinkius Marketplace. 3. Ask your agent a question—for example: 'Show me call analytics for last week'—and let it run the necessary tools automatically. ## Frequently Asked Questions **How do I use get_call_analytics? ** You tell your agent which time frame you want metrics for. The server runs `get_call_analytics` and gives you aggregate numbers like total calls or average duration. **What is the difference between list_campaigns and get_campaign_details? ** `list_campaigns` just spits out a roster of all campaign names. You must use `get_campaign_details` next, providing the specific ID, to see its actual setup. **Can search_calls find calls from last year? ** Yes, as long as you specify a date range that includes those records. You need to provide enough context (date/number) for `search_calls` to work. **Do I need get_account_details before searching calls? ** No, but it's good practice. If you run `get_account_details`, your agent knows which account scope to limit the search to when running `search_calls`. **How do I handle authentication when running list_accounts?** You must provide your Marchex Client ID and Secret credentials. The server uses these to authenticate your AI client against the platform, ensuring secure access before listing accounts. **What specific metadata does get_call_details return for a single call?** It returns detailed records including the caller's number, connection duration, final status (e.g., answered, busy), and which campaign triggered the call. **If I run many searches, how does the server handle rate limiting for search_calls?** The Vinkius platform manages standard API rate limits. We recommend your agent implements smart retry logic or groups related calls into fewer, larger batches to avoid throttling. **What error message should I expect if the ID used in get_campaign_details is invalid?** You'll receive a clear API error (likely 404) stating that the specified resource does not exist. This lets your agent recognize bad input and adjust its workflow without crashing. **How do I find my Marchex Client ID and Secret?** Log in to the Marchex Developer Console and create an application to receive your credentials. **What call data can I access?** You can access call metadata, duration, caller info, status, and aggregated performance metrics. **Is my integration secure?** Absolutely. Your credentials are encrypted at rest and injected securely at runtime.