@pokutuna/mcp-chrome-tabs 0.1.4

package/README.md

@@ -0,0 +1,78 @@
+# @pokutuna/mcp-chrome-tabs
+
+> [!NOTE]
+> **macOS only** - This MCP server uses AppleScript and only works on macOS.
+
+Model Context Protocol (MCP) server that provides direct access to your browser's open tabs content. No additional fetching or authentication required - simply access what you're already viewing.
+
+## Features
+
+- **Access browser tabs** - Direct access to content from tabs currently open in your browser
+- **Active tab shortcut** - Quick reference to currently active tab without specifying tab ID
+- **URL opening** - Open AI-provided URLs directly in new browser tabs
+- **Tools & Resources** - Dual interface supporting both MCP tools and resources with automatic refresh notifications when tab collection changes
+
+## Installation
+
+> [!IMPORTANT]
+> **Requirements**: Enable "Allow JavaScript from Apple Events" in Chrome
+> - (en) **View** > **Developer** > **Allow JavaScript from Apple Events**
+> - (ja) **表示** > **開発 / 管理** > **Apple Events からのJavaScript を許可**
+
+### Manual Configuration
+Add to your MCP configuration file (e.g., `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "chrome-tabs": {
+      "command": "npx",
+      "args": ["-y", "@pokutuna/mcp-chrome-tabs"]
+    }
+  }
+}
+```
+
+### For Claude Code
+```bash
+claude mcp add -s user chrome-tabs -- npx -y @pokutuna/mcp-chrome-tabs
+```
+
+### Command Line Options
+The server accepts optional command line arguments for configuration:
+
+- `--application-name` - Application name to control (default: "Google Chrome")
+- `--exclude-hosts` - Comma-separated list of domains to exclude from tab listing and content access
+- `--check-interval` - Interval in milliseconds to check for tab changes and notify clients (default: 3000, set to 0 to disable)
+
+
+## Tools
+
+### `list_tabs`
+List all open tabs in the user's browser with their titles, URLs, and tab references.
+- Returns: Markdown formatted list of tabs with tab IDs for reference
+
+### `read_tab_content`
+Get readable content from a tab in the user's browser.
+- `id` (optional): Tab reference from `list_tabs` output (e.g., `ID:12345:67890`)
+- If `id` is omitted, uses the currently active tab
+- Returns: Clean, readable content extracted using Mozilla Readability
+
+### `open_in_new_tab`
+Open a URL in a new tab to present content or enable user interaction with webpages.
+- `url` (required): URL to open in the browser
+
+## Resources
+
+### `tab://current`
+Resource representing the content of the currently active tab.
+- **URI**: `tab://current`
+- **MIME type**: `text/markdown`
+- **Content**: Real-time content of the active browser tab
+
+### `tab://{windowId}/{tabId}`
+Resource template for accessing specific tabs.
+- **URI pattern**: `tab://{windowId}/{tabId}`
+- **MIME type**: `text/markdown`
+- **Content**: Content of the specified tab
+- Resources are dynamically generated based on currently open tabs

package/dist/chrome.d.ts

@@ -0,0 +1,16 @@
+export type TabRef = {
+    windowId: string;
+    tabId: string;
+};
+export type Tab = TabRef & {
+    title: string;
+    url: string;
+};
+export type TabContent = {
+    title: string;
+    url: string;
+    content: string;
+};
+export declare function getChromeTabList(applicationName: string): Promise<Tab[]>;
+export declare function getPageContent(applicationName: string, tab?: TabRef | null): Promise<TabContent>;
+export declare function openURL(applicationName: string, url: string): Promise<void>;

package/dist/chrome.js

@@ -0,0 +1,156 @@
+import { execFile } from "child_process";
+import { JSDOM } from "jsdom";
+import { Readability } from "@mozilla/readability";
+import { promisify } from "util";
+import TurndownService from "turndown";
+import turndownPluginGfm from "turndown-plugin-gfm";
+const execFileAsync = promisify(execFile);
+function escapeAppleScript(str) {
+    return str
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r");
+}
+export async function getChromeTabList(applicationName) {
+    const sep = separator();
+    const appleScript = `
+    tell application "${applicationName}"
+      set output to ""
+      repeat with aWindow in (every window)
+        set windowId to id of aWindow
+        repeat with aTab in (every tab of aWindow)
+          set tabId to id of aTab
+          set tabTitle to title of aTab
+          set tabURL to URL of aTab
+          set output to output & windowId & "${sep}" & tabId & "${sep}" & tabTitle & "${sep}" & tabURL & "\\n"
+        end repeat
+      end repeat
+      return output
+    end tell
+  `;
+    const result = await executeAppleScript(appleScript);
+    const lines = result.trim().split("\n");
+    const tabs = [];
+    for (const line of lines) {
+        const [wId, tId, title, url] = line.split(sep);
+        if (!/^https?:\/\//.test(url))
+            continue;
+        tabs.push({
+            windowId: wId,
+            tabId: tId,
+            title: title.trim(),
+            url: url.trim(),
+        });
+    }
+    return tabs;
+}
+export async function getPageContent(applicationName, tab) {
+    const sep = separator();
+    const inner = `
+    set tabTitle to title
+    set tabURL to URL
+    set tabContent to execute javascript "document.documentElement.outerHTML"
+    return tabTitle & "${sep}" & tabURL & "${sep}" & tabContent
+  `;
+    const appleScript = tab
+        ? `
+      try
+        tell application "${applicationName}"
+          tell window id "${tab.windowId}"
+            tell tab id "${tab.tabId}"
+              (* Chrome によって suspend されたタブで js を実行すると動作が停止する
+                 タイムアウトにより osascript コマンドの実行を retry したくないので
+                 apple script 内で timeout をしてエラーを返すようにする *)
+              with timeout of 3 seconds
+                ${inner}
+              end timeout
+            end tell
+          end tell
+        end tell
+      on error errMsg
+        return "ERROR" & "${sep}" & errMsg
+      end try
+    `
+        : `
+      try
+        tell application "${applicationName}"
+          repeat with w in windows
+            tell w
+              set t to tab (active tab index)
+              if URL of t is not "about:blank" then
+                tell t
+                  ${inner}
+                end tell
+              end if
+            end tell
+          end repeat
+          error "No active tab found"
+        end tell
+      on error errMsg
+        return "ERROR" & "${sep}" & errMsg
+      end try
+    `;
+    const result = await executeAppleScript(appleScript);
+    if (result.startsWith(`ERROR${sep}`))
+        throw new Error(result.split(sep)[1]);
+    const parts = result.split(sep).map((part) => part.trim());
+    if (parts.length < 3)
+        throw new Error("Failed to read the tab content");
+    const [title, url, content] = parts;
+    const dom = new JSDOM(content, { url });
+    const reader = new Readability(dom.window.document, {
+        charThreshold: 10,
+    });
+    const article = reader.parse();
+    if (!article?.content)
+        throw new Error("Failed to parse the page content");
+    const turndownService = new TurndownService();
+    turndownService.use(turndownPluginGfm.gfm);
+    const md = turndownService.turndown(article.content);
+    return {
+        title,
+        url,
+        content: md,
+    };
+}
+export async function openURL(applicationName, url) {
+    const escapedUrl = escapeAppleScript(url);
+    const appleScript = `
+    tell application "${applicationName}"
+      open location "${escapedUrl}"
+    end tell
+  `;
+    await executeAppleScript(appleScript);
+}
+async function retry(fn, options) {
+    const { maxRetries = 2, retryDelay = 1000 } = options || {};
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (attempt === maxRetries) {
+                console.error("retry failed after maximum attempts:", error);
+                throw error;
+            }
+            await new Promise((resolve) => setTimeout(resolve, retryDelay * Math.pow(2, attempt)));
+        }
+    }
+    throw new Error("unreachable");
+}
+async function executeAppleScript(script) {
+    return retry(async () => {
+        const { stdout, stderr } = await execFileAsync("osascript", ["-e", script], {
+            timeout: 5 * 1000,
+            maxBuffer: 5 * 1024 * 1024, // 5MB
+        });
+        if (stderr)
+            console.error("AppleScript stderr:", stderr);
+        return stdout.trim();
+    });
+}
+function separator() {
+    const uniqueId = Math.random().toString(36).substring(2);
+    return `<|SEP:${uniqueId}|>`;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { parseArgs } from "util";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "./mcp.js";
+function showHelp() {
+    console.log(`
+MCP Chrome Tabs Server
+
+USAGE:
+  mcp-chrome-tabs [OPTIONS]
+
+OPTIONS:
+  --application-name=<name>    Application name to control via AppleScript
+                               (default: "Google Chrome")
+                               Example: "Google Chrome Canary"
+
+  --exclude-hosts=<hosts>      Comma-separated list of hosts to exclude
+                               (default: "")
+                               Example: "github.com,example.com,test.com"
+
+  --check-interval=<ms>        Interval for checking browser tabs in milliseconds
+                               (default: 3000, set to 0 to disable)
+                               Example: 1000
+
+  --help                       Show this help message
+
+
+REQUIREMENTS:
+  Chrome must allow JavaScript from Apple Events:
+  1. Open Chrome
+  2. Go to View > Developer > Allow JavaScript from Apple Events
+  3. Enable the option
+
+MCP CONFIGURATION EXAMPLE:
+  {
+    "mcpServers": {
+      "chrome-tabs": {
+        "command": "npx",
+        "args": ["-y", "@pokutuna/mcp-chrome-tabs"]
+      }
+    }
+  }
+`.trimStart());
+}
+function parseCliArgs(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            "application-name": {
+                type: "string",
+                default: "Google Chrome",
+            },
+            "exclude-hosts": {
+                type: "string",
+                default: "",
+            },
+            "check-interval": {
+                type: "string",
+                default: "3000",
+            },
+            help: {
+                type: "boolean",
+                default: false,
+            },
+        },
+        allowPositionals: false,
+        tokens: true,
+    });
+    const parsed = {
+        applicationName: values["application-name"],
+        excludeHosts: values["exclude-hosts"]
+            .split(",")
+            .map((d) => d.trim())
+            .filter(Boolean),
+        checkInterval: parseInt(values["check-interval"], 10),
+        help: values.help,
+    };
+    return parsed;
+}
+const options = parseCliArgs(process.argv.slice(2));
+if (options.help) {
+    showHelp();
+    process.exit(0);
+}
+const server = await createMcpServer(options);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/mcp.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export type McpServerOptions = {
+    applicationName: string;
+    excludeHosts: string[];
+    checkInterval: number;
+};
+export declare function createMcpServer(options: McpServerOptions): Promise<McpServer>;

package/dist/mcp.js

@@ -0,0 +1,177 @@
+import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import * as chrome from "./chrome.js";
+import { readFile } from "fs/promises";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { createHash } from "crypto";
+import * as view from "./view.js";
+function isExcludedHost(url, excludeHosts) {
+    const u = new URL(url);
+    return excludeHosts.some((d) => u.hostname === d || u.hostname.endsWith("." + d));
+}
+async function listTabs(opts) {
+    const tabs = await chrome.getChromeTabList(opts.applicationName);
+    return tabs.filter((t) => !isExcludedHost(t.url, opts.excludeHosts));
+}
+async function getTab(tabRef, opts) {
+    const content = await chrome.getPageContent(opts.applicationName, tabRef);
+    if (isExcludedHost(content.url, opts.excludeHosts)) {
+        throw new Error("Content not available for excluded host");
+    }
+    return content;
+}
+async function packageVersion() {
+    const packageJsonText = await readFile(join(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8");
+    const packageJson = JSON.parse(packageJsonText);
+    return packageJson.version;
+}
+function hashTabList(tabs) {
+    const sortedTabs = tabs.slice().sort((a, b) => {
+        if (a.windowId !== b.windowId)
+            return a.windowId < b.windowId ? -1 : 1;
+        if (a.tabId !== b.tabId)
+            return a.tabId < b.tabId ? -1 : 1;
+        return 0;
+    });
+    const dump = sortedTabs
+        .map((tab) => `${tab.windowId}:${tab.tabId}:${tab.title}:${tab.url}`)
+        .join("|");
+    return createHash("sha256").update(dump, "utf8").digest("hex");
+}
+export async function createMcpServer(options) {
+    const server = new McpServer({
+        name: "chrome-tabs",
+        version: await packageVersion(),
+    }, {
+        capabilities: {
+            resources: {
+                listChanged: true,
+            },
+        },
+        debouncedNotificationMethods: ["notifications/resources/list_changed"],
+    });
+    server.registerTool("list_tabs", {
+        description: "List all open tabs in the user's browser with their titles, URLs, and tab references",
+        inputSchema: {},
+    }, async () => {
+        const tabs = await listTabs(options);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: view.formatList(tabs),
+                },
+            ],
+        };
+    });
+    server.registerTool("read_tab_content", {
+        description: "Get readable content from a tab in the user's browser. Provide ID (from list_tabs output) to read a specific tab, or omit for the active tab.",
+        inputSchema: {
+            id: z
+                .string()
+                .optional()
+                .describe("Tab reference from list_tabs output (e.g: ID:12345:67890). If omitted, uses the currently active tab."),
+        },
+    }, async (args) => {
+        const { id } = args;
+        const tab = await getTab(id ? view.parseTabRef(id) : null, options);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: view.formatTabContent(tab),
+                },
+            ],
+        };
+    });
+    server.registerTool("open_in_new_tab", {
+        description: "Open a URL in a new tab to present content or enable user interaction with webpages",
+        inputSchema: {
+            url: z.string().url().describe("URL to open in the browser"),
+        },
+    }, async (args) => {
+        const { url } = args;
+        await chrome.openURL(options.applicationName, url);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Successfully opened the URL`,
+                },
+            ],
+        };
+    });
+    server.registerResource("current_tab", "tab://current", {
+        title: "Active Browser Tab",
+        description: "Content of the currently active tab in the user's browser",
+        mimeType: "text/markdown",
+    }, async (uri) => {
+        const tab = await getTab(null, options);
+        const text = view.formatTabContent(tab);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    name: tab.title,
+                    text,
+                    mimeType: "text/markdown",
+                    size: new Blob([text]).size,
+                },
+            ],
+        };
+    });
+    server.registerResource("tabs", new ResourceTemplate(view.uriTemplate, {
+        list: async () => {
+            const tabs = await listTabs(options);
+            return {
+                resources: tabs.map((tab) => ({
+                    uri: view.formatUri(tab),
+                    name: tab.title,
+                    mimeType: "text/markdown",
+                })),
+            };
+        },
+    }), {
+        title: "Browser Tabs",
+        description: "Content of a specific tab in the user's browser",
+        mimeType: "text/markdown",
+    }, async (uri, { windowId, tabId }) => {
+        const tabRef = {
+            windowId: String(windowId),
+            tabId: String(tabId),
+        };
+        const tab = await getTab(tabRef, options);
+        const text = view.formatTabContent(tab);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    name: tab.title,
+                    mimeType: "text/markdown",
+                    text,
+                    size: new Blob([text]).size,
+                },
+            ],
+        };
+    });
+    if (options.checkInterval > 0) {
+        let lastHash = hashTabList(await listTabs(options));
+        const check = async () => {
+            try {
+                const hash = hashTabList(await listTabs(options));
+                if (hash !== lastHash) {
+                    server.sendResourceListChanged();
+                    lastHash = hash;
+                }
+            }
+            catch (error) {
+                console.error("Error during periodic tab list update:", error);
+            }
+            // Use setTimeout instead of setInterval to avoid overlapping calls
+            setTimeout(check, options.checkInterval);
+        };
+        check();
+    }
+    return server;
+}

package/dist/view.d.ts

@@ -0,0 +1,8 @@
+import { Tab, TabRef, TabContent } from "./chrome.js";
+export declare function formatTabRef(tab: Tab): string;
+export declare function parseTabRef(tabRef: string): TabRef | null;
+export declare function formatList(tabs: Tab[]): string;
+export declare function formatListItem(tab: Tab): string;
+export declare function formatTabContent(tab: TabContent): string;
+export declare const uriTemplate = "tab://{windowId}/{tabId}";
+export declare function formatUri(ref: TabRef): string;

package/dist/view.js

@@ -0,0 +1,38 @@
+export function formatTabRef(tab) {
+    return `ID:${tab.windowId}:${tab.tabId}`;
+}
+export function parseTabRef(tabRef) {
+    const match = tabRef.match(/ID:(\d+):(\d+)$/);
+    if (!match)
+        return null;
+    const windowId = match[1];
+    const tabId = match[2];
+    return { windowId, tabId };
+}
+function truncateUrl(tab, over = 120) {
+    const url = tab.url;
+    if (url.length <= over)
+        return url;
+    return url.slice(0, over) + "...";
+}
+export function formatList(tabs) {
+    const list = tabs.map(formatListItem).join("\n");
+    const header = `### Current Tabs (${tabs.length} tabs exists)\n`;
+    return header + list;
+}
+export function formatListItem(tab) {
+    return `- ${formatTabRef(tab)} [${tab.title}](${truncateUrl(tab)})`;
+}
+export function formatTabContent(tab) {
+    return `
+---
+title: ${tab.title}
+---
+${tab.content}
+`.trimStart();
+}
+export const uriTemplate = "tab://{windowId}/{tabId}";
+export function formatUri(ref) {
+    // TODO give domain & title for incremental search
+    return `tab://${ref.windowId}/${ref.tabId}`;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@pokutuna/mcp-chrome-tabs",
+  "version": "0.1.4",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pokutuna/mcp-chrome-tabs"
+  },
+  "type": "module",
+  "bin": {
+    "mcp-chrome-tabs": "./dist/cli.js"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "node --import tsx src/cli.ts",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "inspector": "npx @modelcontextprotocol/inspector",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.16.0",
+    "@mozilla/readability": "^0.6.0",
+    "jsdom": "^26.1.0",
+    "turndown": "^7.2.0",
+    "turndown-plugin-gfm": "^1.0.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^20.11.17",
+    "@types/turndown": "^5.0.5",
+    "tsx": "^4.7.1",
+    "typescript": "~5.8.3",
+    "vitest": "^3.2.4"
+  }
+}