URL-Context-MCP MCP Server

The URL-Context-MCP MCP Server provides a tool to analyze and summarize the content of URLs using Google Gemini's URL Context capability via the Gemini API.

Now also supports optional grounding with Google Search alongside URL Context. The server is designed to follow prompt-only orchestration: control whether to search or scrape via the instruction text you provide.

Installation

Prerequisites

• Node.js 18+
• Set GOOGLE_API_KEY in your environment

Get a Gemini API key

• Sign in to Google AI for Developers and create an API key
  • See: Gemini API API keys guide
• Copy the generated key and set it as GOOGLE_API_KEY for this server
  • Cursor (project): add to .cursor/mcp.json under env
  • Claude CLI one-liner example: shown below
  • Or set it in your shell before launching

Published Package

This MCP server is now available as a published npm package: @taiyokimura/url-context-mcp

• No need to clone the repository locally
• Can be run directly via npx @taiyokimura/url-context-mcp@latest
• See setup instructions below for Cursor and Claude Code

Build locally

cd /Users/kimurataiyou/url-context-mcp
npm i
npm run build

Setup: Claude Code (CLI)

Use this one-line command (replace with your real API key):

claude mcp add URL-Context-MCP -s user -e GOOGLE_API_KEY="sk-your-real-key" -- npx @taiyokimura/url-context-mcp@latest

To remove the server from Claude Code:

claude mcp remove URL-Context-MCP

Setup: Cursor

Create .cursor/mcp.json at your repository root:

{
  "mcpServers": {
    "URL-Context-MCP": {
      "command": "npx",
      "args": ["@taiyokimura/url-context-mcp@latest"],
      "env": { "GOOGLE_API_KEY": "sk-your-real-key" },
      "autoStart": true
    }
  }
}

Other Clients and Agents

Install in VS Code
Install in VS Code Insiders

Or add via CLI:

code --add-mcp '{"name":"URL-Context-MCP","command":"npx","args":["@taiyokimura/url-context-mcp@latest"],"env":{"GOOGLE_API_KEY":"sk-your-real-key"}}'

Follow the MCP install guide and use the standard config above:

• Guide: https://modelcontextprotocol.io/quickstart/user

Add MCP Server with:

• Command: npx
• Args: ["@taiyokimura/url-context-mcp@latest"]
• Env: GOOGLE_API_KEY=sk-your-real-key

Advanced settings Extensions Add custom extension:

• Type: STDIO
• Command: npx
• Args: @taiyokimura/url-context-mcp@latest
• Enabled: true

Example ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "url-context-mcp": {
      "type": "local",
      "command": [
        "npx",
        "@taiyokimura/url-context-mcp@latest"
      ],
      "enabled": true
    }
  }
}

Open Qodo Gen (VSCode/IntelliJ) Connect more tools + Add new MCP Paste the standard config JSON Save.

Follow Windsurf MCP documentation and use the standard config above:

• Docs: https://docs.windsurf.com/windsurf/cascade/mcp

Configuration (Env)

• GOOGLE_API_KEY: Your Gemini API key

Available Tools

• analyze_urls
  • inputs:
    • urls: string | string[] (1-20 total)
    • instruction?: string
    • model?: string (default: gemini-2.5-flash)
    • use_google_search?: boolean (default: false) enable grounding with Google Search in addition to URL Context

Prompt recipes (prompt-only orchestration)

• Scraping-only (user provided URLs). Example instruction:
  • "貼URLURL解析要約引用URL日本語提示外部検索禁止取得失敗明示"
• Research with search + scraping, iterative up to 5 rounds. Example instruction:
  • "以下調査Google検索候補収集引用全URL必URL取得要約統合不十分最大5回再検索再収集補完日本語簡潔要約引用URL提示"

Example invocation (MCP tool call)

{
  "name": "analyze_urls",
  "arguments": {
    "urls": "https://note.com/hawk735/n/nbc585d0774df",
    "instruction": "日本語要約引用URL簡潔",
    "use_google_search": true
  }
}

Scraping-only example

{
  "name": "analyze_urls",
  "arguments": {
    "urls": ["https://example.com/post1", "https://example.com/post2"],
    "instruction": "貼URLURL解析要約引用URL日本語提示外部検索禁止取得失敗明示"
  }
}

Research + scraping (iterative) example

{
  "name": "google_search",
  "arguments": {
    "query": "最新Next.js 14App Router",
    "instruction": "Google検索候補収集引用全URL必URL取得要約統合不十分最大5回再検索再収集補完日本語簡潔要約引用URL提示"
  }
}

Troubleshooting

• 401 auth errors: verify GOOGLE_API_KEY
• Ensure Node 18+
• For npx usage: npx @taiyokimura/url-context-mcp@latest should work without local build
• For local development: use absolute path to build/index.js

References

• Model Context Protocol Quickstart
• MCP SDK Docs
• Gemini API URL context