search-console-mcp 1.11.1 → 1.12.0

package/README.md

@@ -13,17 +13,23 @@ A Model Context Protocol (MCP) server that transforms how you interact with **Go
 ## Why use this?
 
 ### ❌ The Old Way
-1.  Open Search Console -> Performance Tab
-2.  Filter by "Last 28 days"
-3.  Export to CSV
-4.  Open in Excel/Sheets
-5.  Create a filter for "Position > 10" AND "Impressions > 1000"
-6.  Analyze manually to find opportunities
+1.  Open Google Search Console → Export CSV
+2.  Open Bing Webmaster Tools → Export CSV
+3.  Paste both into a spreadsheet
+4.  Manually compare keywords across engines
+5.  Switch between accounts for different clients
+6.  Repeat weekly
 
 ### ✅ The New Way
 **Just ask:**
 > "Find low-hanging fruit keywords (positions 11-20) with high impressions that I should optimize."
 
+> "Compare my Google and Bing performance — where am I leaving Bing traffic on the table?"
+
+> "Run a health check across all my sites and give me 3 actions for next week."
+
+**One server. Both engines. Multiple accounts. Zero spreadsheets.**
+
 ---
 ## 🎯 Magic Prompts
 
@@ -47,15 +53,21 @@ Copy and paste these into your MCP client (Claude Desktop, etc.) to see the inte
 #### ⚡ The Speed vs. Ranking Correlator
 > "Fetch the top 5 pages by impressions. For these pages, run a PageSpeed audit. Is there any correlation between low performance scores and recently declining positions?"
 
-#### 🔍 Multi-Engine Comparison
+#### 🔀 Multi-Engine Comparison
 > "Compare my performance between Google and Bing for the last 30 days. Which keywords are ranking better on Bing but have lower traffic on Google?"
 
+#### 🎯 Bing Opportunity Finder
+> "Show me keywords where I'm in the top 5 on Google but not ranking on Bing. These are my easy Bing wins."
+
+#### ⚠️ Google Dependency Check
+> "Am I too dependent on Google? Check my click share across both engines and flag any keywords where over 85% of traffic comes from Google."
+
 ---
 
 ## 🔐 Authentication (Desktop Flow)
 
 Search Console MCP uses a **Secure Desktop Flow**. This provides high-security, professional grade authentication for your Google account:
-- **Multi-Account Support**: Automatically detects and stores separate tokens for different Google accounts based on your email.
+- **Multi-Account Support**: Connect multiple Google and Bing accounts. The server automatically picks the right one for each site.
 - **System Keychain Primary**: Tokens are stored in your OS's native credential manager (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
 - **AES-256-GCM Hardware-Bound Encryption**: Fallback storage is encrypted with AES-256-GCM using a key derived from your unique hardware machine ID. Tokens stolen from your machine cannot be decrypted on another computer.
 - **Silent Background Refresh**: Tokens auto-refresh silently when they expire.
@@ -112,16 +124,36 @@ To access Bing data, you simply need an API Key.
 
 ---
 
+## 👥 Multi-Account Management
+
+Manage multiple Google and Bing accounts from the CLI:
+
+```bash
+# List all connected accounts
+npx search-console-mcp accounts list
+
+# Remove an account
+npx search-console-mcp accounts remove --account=marketing@company.com
+
+# Add a site boundary to an account
+npx search-console-mcp accounts add-site --account=marketing@company.com --site=example.com
+```
+
+When your AI agent queries a site, the server automatically resolves which account to use. [Learn more →](https://searchconsolemcp.mintlify.app/getting-started/multi-account)
+
+---
+
 
 ## 🛡️ Fort Knox Security
 
 This MCP server implements a multi-layered security architecture:
 
 *   **Keychain Integration**: Primarily uses the **macOS Keychain**, **Windows Credential Manager**, or **libsecret (Linux)** to store tokens.
-*   **Hardware-Bound Vault**: Fallback tokens are stored in `~/.search-console-mcp-tokens.enc` and encrypted with **AES-256-GCM**.
+*   **Encrypted Config**: Account configuration is stored in `~/.search-console-mcp-config.enc` using **AES-256-GCM** encryption.
 *   **Machine Fingerprinting**: The encryption key is derived from your unique hardware UUID and OS user. The encrypted file is useless if moved to another machine.
 *   **Minimalist Storage**: Only the `refresh_token` and `expiry_date` are stored.
-*   **Strict Unix Permissions**: The fallback file is created with `mode 600` (read/write only by your user).
+*   **Legacy Support**: Automatically detects credentials from older versions (tokens files, environment variables).
+*   **Strict Unix Permissions**: Config files are created with `mode 600` (read/write only by your user).
 
 ---
 

package/dist/accounts.js

@@ -0,0 +1,209 @@
+import { loadConfig, removeAccount, updateAccount } from './common/auth/config.js';
+function parseFlags(args) {
+    const flags = {};
+    for (const arg of args) {
+        const match = arg.match(/^--([^=]+)=(.+)$/);
+        if (match) {
+            flags[match[1]] = match[2];
+        }
+    }
+    return flags;
+}
+function findAccountByAliasOrId(accounts, identifier) {
+    // Try exact ID match first
+    if (accounts[identifier])
+        return accounts[identifier];
+    // Then try alias match (case-insensitive)
+    return Object.values(accounts).find((a) => a.alias?.toLowerCase() === identifier.toLowerCase() || a.id === identifier);
+}
+export async function main(args) {
+    const subcommand = args[0] || 'list';
+    const flags = parseFlags(args.slice(1));
+    // Positional args (non-flag args after the subcommand)
+    const positional = args.slice(1).filter(a => !a.startsWith('--'));
+    if (subcommand === 'list') {
+        try {
+            const config = await loadConfig();
+            const accounts = Object.values(config.accounts);
+            if (accounts.length === 0) {
+                console.log(JSON.stringify({
+                    accounts: [],
+                    message: "No accounts connected.",
+                    resolution: {
+                        command: "search-console-mcp setup",
+                        google: "search-console-mcp setup --engine=google",
+                        bing: "search-console-mcp setup --engine=bing"
+                    },
+                    setup_instructions: {
+                        google: [
+                            "Run: search-console-mcp setup --engine=google",
+                            "Choose OAuth 2.0 login or Service Account",
+                            "Authorize in browser and select sites to restrict (or allow all)"
+                        ],
+                        bing: [
+                            "Run: search-console-mcp setup --engine=bing",
+                            "Get your API key from https://www.bing.com/webmasters/settings/api",
+                            "Enter the API key when prompted"
+                        ]
+                    }
+                }, null, 2));
+                return;
+            }
+            const siteRows = [];
+            for (const a of accounts) {
+                const alias = a.alias || '[Unnamed]';
+                const engine = a.engine === 'google' ? 'Google' : 'Bing';
+                if (!a.websites || a.websites.length === 0) {
+                    siteRows.push({
+                        site: '[All Sites Authorized]',
+                        account: alias,
+                        engine: engine,
+                        id: a.id
+                    });
+                }
+                else {
+                    for (const site of a.websites) {
+                        siteRows.push({
+                            site: site,
+                            account: alias,
+                            engine: engine,
+                            id: a.id
+                        });
+                    }
+                }
+            }
+            console.log(JSON.stringify({ accounts: siteRows }, null, 2));
+        }
+        catch (error) {
+            console.log(JSON.stringify({
+                error: "Failed to list accounts",
+                message: error.message
+            }, null, 2));
+        }
+        return;
+    }
+    if (subcommand === 'remove') {
+        // Flags (agent): --account=alias --site=url  |  Positional (human): remove <alias_or_site>
+        const identifier = flags['account'] || flags['id'] || positional[0];
+        const siteToRemove = flags['site'];
+        if (!identifier && !siteToRemove) {
+            console.log(JSON.stringify({
+                error: "Missing arguments",
+                message: "Provide --account=<alias|id> to remove an account, or --site=<url> to remove a specific site boundary.",
+                resolution: {
+                    by_account: "search-console-mcp accounts remove --account=<alias_or_id>",
+                    by_site: "search-console-mcp accounts remove --site=<siteUrl>"
+                }
+            }, null, 2));
+            return;
+        }
+        try {
+            const config = await loadConfig();
+            if (identifier) {
+                // Remove entire account by alias or ID
+                const account = findAccountByAliasOrId(config.accounts, identifier);
+                if (!account) {
+                    console.log(JSON.stringify({
+                        error: "Account not found",
+                        message: `No account matching '${identifier}' was found.`,
+                        resolution: "Run: search-console-mcp accounts list"
+                    }, null, 2));
+                    return;
+                }
+                await removeAccount(account.id);
+                console.log(JSON.stringify({
+                    success: true,
+                    message: `Account '${account.alias}' (${account.id}) removed successfully.`
+                }, null, 2));
+            }
+            else if (siteToRemove) {
+                // Remove a specific site boundary from whichever account owns it
+                let found = false;
+                for (const account of Object.values(config.accounts)) {
+                    if (account.websites?.includes(siteToRemove)) {
+                        account.websites = account.websites.filter((w) => w !== siteToRemove);
+                        await updateAccount(account);
+                        found = true;
+                        console.log(JSON.stringify({
+                            success: true,
+                            message: `Site '${siteToRemove}' removed from account '${account.alias}'.`
+                        }, null, 2));
+                        break;
+                    }
+                }
+                if (!found) {
+                    console.log(JSON.stringify({
+                        error: "Site not found",
+                        message: `No account has '${siteToRemove}' in its site boundaries.`,
+                        resolution: "Run: search-console-mcp accounts list"
+                    }, null, 2));
+                }
+            }
+        }
+        catch (error) {
+            console.log(JSON.stringify({
+                error: "Failed to remove",
+                message: error.message
+            }, null, 2));
+        }
+        return;
+    }
+    if (subcommand === 'add-site') {
+        // Flags (agent): --account=alias --site=url  |  Positional (human): add-site <alias> <site>
+        const identifier = flags['account'] || flags['id'] || positional[0];
+        const site = flags['site'] || positional[1];
+        if (!identifier || !site) {
+            console.log(JSON.stringify({
+                error: "Missing arguments",
+                message: "Both --account and --site are required.",
+                resolution: "search-console-mcp accounts add-site --account=<alias_or_id> --site=<siteUrl>"
+            }, null, 2));
+            return;
+        }
+        try {
+            const config = await loadConfig();
+            const account = findAccountByAliasOrId(config.accounts, identifier);
+            if (!account) {
+                console.log(JSON.stringify({
+                    error: "Account not found",
+                    message: `No account matching '${identifier}' was found.`,
+                    resolution: "Run: search-console-mcp accounts list"
+                }, null, 2));
+                return;
+            }
+            if (!account.websites)
+                account.websites = [];
+            if (!account.websites.includes(site)) {
+                account.websites.push(site);
+                await updateAccount(account);
+                console.log(JSON.stringify({
+                    success: true,
+                    message: `Site '${site}' added to account '${account.alias}'.`
+                }, null, 2));
+            }
+            else {
+                console.log(JSON.stringify({
+                    success: true,
+                    message: `Account '${account.alias}' already has '${site}' in its boundaries.`
+                }, null, 2));
+            }
+        }
+        catch (error) {
+            console.log(JSON.stringify({
+                error: "Failed to add site",
+                message: error.message
+            }, null, 2));
+        }
+        return;
+    }
+    console.log(JSON.stringify({
+        error: "Unknown command",
+        message: `'${subcommand}' is not a valid subcommand.`,
+        resolution: {
+            list: "search-console-mcp accounts list",
+            remove_account: "search-console-mcp accounts remove --account=<alias_or_id>",
+            remove_site: "search-console-mcp accounts remove --site=<siteUrl>",
+            add_site: "search-console-mcp accounts add-site --account=<alias_or_id> --site=<siteUrl>"
+        }
+    }, null, 2));
+}

package/dist/bing/client.js

@@ -1,3 +1,5 @@
+import { resolveAccount } from '../common/auth/resolver.js';
+import { loadConfig } from '../common/auth/config.js';
 export class BingClient {
     apiKey;
     baseUrl = 'https://ssl.bing.com/webmaster/api.svc/json';
@@ -93,14 +95,41 @@ export class BingClient {
         return this.request('GetRelatedKeywords', { q, country, language });
     }
 }
-let cachedBingClient = null;
-export async function getBingClient() {
-    if (cachedBingClient)
-        return cachedBingClient;
-    const apiKey = process.env.BING_API_KEY;
+let cachedBingClients = {};
+export async function getBingClient(siteUrl, accountId) {
+    // 1. Resolve Account
+    let apiKey;
+    let cacheKey;
+    if (accountId) {
+        const config = await loadConfig();
+        const account = config.accounts[accountId];
+        if (!account || account.engine !== 'bing') {
+            throw new Error(`Bing account ${accountId} not found.`);
+        }
+        apiKey = account.apiKey;
+        cacheKey = account.id;
+    }
+    else {
+        try {
+            const account = await resolveAccount(siteUrl || '', 'bing');
+            apiKey = account.apiKey;
+            cacheKey = account.id;
+        }
+        catch (error) {
+            // Fallback to environment variable for legacy support if resolution fails or no site specified
+            apiKey = process.env.BING_API_KEY;
+            cacheKey = 'env_fallback';
+            if (!apiKey) {
+                throw error; // Re-throw the resolution error if no ENV fallback either
+            }
+        }
+    }
+    if (cachedBingClients[cacheKey])
+        return cachedBingClients[cacheKey];
     if (!apiKey) {
-        throw new Error('Bing API Key not found. Please set BING_API_KEY environment variable or run setup.');
+        throw new Error('Bing API Key not found. Please run setup to add an account.');
     }
-    cachedBingClient = new BingClient(apiKey);
-    return cachedBingClient;
+    const client = new BingClient(apiKey);
+    cachedBingClients[cacheKey] = client;
+    return client;
 }

package/dist/bing/tools/analytics.js

@@ -1,37 +1,69 @@
 import { getBingClient } from '../client.js';
 /**
- * Get query performance stats for a Bing site.
+ * Get query performance stats for a Bing site with optional date filtering.
  */
-export async function getQueryStats(siteUrl) {
-    const client = await getBingClient();
-    return client.getQueryStats(siteUrl);
+export async function getQueryStats(siteUrl, startDate, endDate) {
+    const client = await getBingClient(siteUrl);
+    const stats = await client.getQueryStats(siteUrl);
+    if (!startDate && !endDate)
+        return stats;
+    const start = startDate ? new Date(startDate) : new Date(0);
+    const end = endDate ? new Date(endDate) : new Date();
+    return stats.filter(row => {
+        const d = new Date(row.Date);
+        return d >= start && d <= end;
+    });
 }
 /**
- * Get page performance stats (top pages) for a Bing site.
+ * Get page performance stats (top pages) for a Bing site with optional date filtering.
  */
-export async function getPageStats(siteUrl) {
-    const client = await getBingClient();
-    return client.getPageStats(siteUrl);
+export async function getPageStats(siteUrl, startDate, endDate) {
+    const client = await getBingClient(siteUrl);
+    const stats = await client.getPageStats(siteUrl);
+    if (!startDate && !endDate)
+        return stats;
+    const start = startDate ? new Date(startDate) : new Date(0);
+    const end = endDate ? new Date(endDate) : new Date();
+    return stats.filter(row => {
+        const d = new Date(row.Date);
+        return d >= start && d <= end;
+    });
 }
 /**
- * Get query stats for a specific page on a Bing site.
+ * Get query stats for a specific page on a Bing site with optional date filtering.
  */
-export async function getPageQueryStats(siteUrl, pageUrl) {
-    const client = await getBingClient();
-    return client.getPageQueryStats(siteUrl, pageUrl);
+export async function getPageQueryStats(siteUrl, pageUrl, startDate, endDate) {
+    const client = await getBingClient(siteUrl);
+    const stats = await client.getPageQueryStats(siteUrl, pageUrl);
+    if (!startDate && !endDate)
+        return stats;
+    const start = startDate ? new Date(startDate) : new Date(0);
+    const end = endDate ? new Date(endDate) : new Date();
+    return stats.filter(row => {
+        const d = new Date(row.Date);
+        return d >= start && d <= end;
+    });
 }
 /**
- * Get combined query and page performance stats.
+ * Get combined query and page performance stats with optional date filtering.
  */
-export async function getQueryPageStats(siteUrl) {
-    const client = await getBingClient();
-    return client.getQueryPageStats(siteUrl);
+export async function getQueryPageStats(siteUrl, startDate, endDate) {
+    const client = await getBingClient(siteUrl);
+    const stats = await client.getQueryPageStats(siteUrl);
+    if (!startDate && !endDate)
+        return stats;
+    const start = startDate ? new Date(startDate) : new Date(0);
+    const end = endDate ? new Date(endDate) : new Date();
+    return stats.filter(row => {
+        const d = new Date(row.Date);
+        return d >= start && d <= end;
+    });
 }
 /**
  * Get historical rank and traffic statistics for a site.
  */
 export async function getRankAndTrafficStats(siteUrl) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     return client.getRankAndTrafficStats(siteUrl);
 }
 /**

package/dist/bing/tools/crawl.js

@@ -10,6 +10,6 @@ export async function getCrawlIssues(siteUrl) {
  * Get crawl statistics for a site.
  */
 export async function getCrawlStats(siteUrl) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     return client.getCrawlStats(siteUrl);
 }

package/dist/bing/tools/inspection.js

@@ -3,6 +3,6 @@ import { getBingClient } from '../client.js';
  * Get detailed indexing and crawl information for a URL.
  */
 export async function getUrlInfo(siteUrl, url) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     return client.getUrlInfo(siteUrl, url);
 }

package/dist/bing/tools/links.js

@@ -3,6 +3,6 @@ import { getBingClient } from '../client.js';
  * Get link counts for a site.
  */
 export async function getLinkCounts(siteUrl) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     return client.getLinkCounts(siteUrl);
 }

package/dist/bing/tools/sitemaps.js

@@ -6,7 +6,7 @@ import { getBingClient } from '../client.js';
  * @returns A list of sitemaps.
  */
 export async function listSitemaps(siteUrl) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     return client.getFeeds(siteUrl);
 }
 /**
@@ -16,7 +16,7 @@ export async function listSitemaps(siteUrl) {
  * @param sitemapUrl - The URL of the sitemap file.
  */
 export async function submitSitemap(siteUrl, sitemapUrl) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     await client.submitSitemap(siteUrl, sitemapUrl);
     return `Successfully submitted sitemap: ${sitemapUrl} for site ${siteUrl}`;
 }
@@ -27,7 +27,7 @@ export async function submitSitemap(siteUrl, sitemapUrl) {
  * @param sitemapUrl - The URL of the sitemap to remove.
  */
 export async function deleteSitemap(siteUrl, sitemapUrl) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     await client.deleteSitemap(siteUrl, sitemapUrl);
     return `Successfully removed sitemap: ${sitemapUrl} for site ${siteUrl}`;
 }

package/dist/bing/tools/sites-health.js

@@ -103,7 +103,7 @@ export async function healthCheck(siteUrl) {
     if (allSites.length === 0) {
         return [];
     }
-    const reports = await Promise.all(allSites.map(site => checkSite(site.Url)));
+    const reports = await Promise.all(allSites.map((site) => checkSite(site.Url)));
     const order = { critical: 0, warning: 1, healthy: 2 };
-    return reports.sort((a, b) => order[a.status] - order[b.status]);
+    return reports.sort((a, b) => (order[a.status] || 0) - (order[b.status] || 0));
 }

package/dist/bing/tools/sites.js

@@ -1,11 +1,12 @@
 import { getBingClient } from '../client.js';
 /**
- * List all sites verified in the user's Bing Webmaster Tools.
+ * List all sites verified in the specified Bing account.
  *
+ * @param accountId - Optional. The account to list sites for.
  * @returns A list of verified site properties.
  */
-export async function listSites() {
-    const client = await getBingClient();
+export async function listSites(accountId) {
+    const client = await getBingClient(undefined, accountId);
     return client.getSiteList();
 }
 /**
@@ -15,7 +16,7 @@ export async function listSites() {
  * @returns A success message.
  */
 export async function addSite(siteUrl) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     await client.addSite(siteUrl);
     return `Successfully added site: ${siteUrl}`;
 }
@@ -26,7 +27,7 @@ export async function addSite(siteUrl) {
  * @returns A success message.
  */
 export async function removeSite(siteUrl) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     await client.removeSite(siteUrl);
     return `Successfully removed site: ${siteUrl}`;
 }

package/dist/bing/tools/url-submission.js

@@ -3,14 +3,14 @@ import { getBingClient } from '../client.js';
  * Get remaining URL submission quota.
  */
 export async function getUrlSubmissionQuota(siteUrl) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     return client.getUrlSubmissionQuota(siteUrl);
 }
 /**
  * Submit a single URL for indexing.
  */
 export async function submitUrl(siteUrl, url) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     await client.submitUrl(siteUrl, url);
     return `Successfully submitted URL: ${url}`;
 }
@@ -18,7 +18,7 @@ export async function submitUrl(siteUrl, url) {
  * Submit a batch of URLs for indexing.
  */
 export async function submitUrlBatch(siteUrl, urlList) {
-    const client = await getBingClient();
+    const client = await getBingClient(siteUrl);
     await client.submitUrlBatch(siteUrl, urlList);
     return `Successfully submitted ${urlList.length} URLs in batch.`;
 }