# mixelpixx/google-search-mcp-server architecture

> Architecture diagram of the GitHub repository mixelpixx/google-search-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mixelpixx/google-search-mcp-server
- Repository: https://github.com/mixelpixx/google-search-mcp-server

## Overview

##### Main Components
- TypeScript MCP Server:
- This is the Node.js-based part (built in TypeScript) responsible for handling MCP protocol communication and providing the tool interface. It is compiled from the files in the src directory (e.g., google-search.ts, content-fetcher.ts, types.ts, etc.) and launched via Node.js.
- Python Flask Server:
- This component is made up of the Python scripts (google_search.py and link_view.py) and handles interactions with Google’s API and webpage content extraction/analysis. It uses Flask and additional Python libraries for tasks such as web scraping (beautifulsoup4, trafilatura) and API interfacing (google-api-python-client).

##### Relationships and Interactions
- Client / MCP Integrations:
- External clients such as the Cline VS Code extension or the Claude desktop app will send commands to the MCP server.
- These clients interact with the Node.js MCP server according to the MCP protocol and tool interface.
- Internal Coordination between Servers:
- Once a request arrives (e.g., a “google_search” or “extract_webpage_content” command), the TypeScript MCP server delegates the task to the Python Flask server.
- API Credential Management:
- Both the Node.js and Python servers rely on API keys (either from environment variables or the api-keys.json file) to authenticate with Google’s Custom Search API.
- A configuration component to show how API credentials are injected.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- Divide the architecture clearly between the MCP protocol handling (Node.js/TypeScript) and Google search + webpage analysis (Python/Flask).
- Modular Design:
- How the different tools (e.g., “google_search”, “extract_webpage_content”, “extract_multiple_webpages”) are implemented as distinct modules or endpoints.
- Environment-Based Configuration:
- Support for both environment variables and configuration files (api-keys.json), which is important for secure and flexible deployments.
- Multi-Language Integration:
- It’s a hybrid system that leverages the strengths of both TypeScript (for high-performance MCP communication) and Python (for web scraping and API interaction).

##### Technologies and Dependencies
- Node.js + TypeScript:
- Shown in the “src” directory (google-search.ts, content-fetcher.ts, etc.) and built into a distributable JavaScript file (as indicated by the build instructions).
- Python + Flask:
- Represented by google_search.py and link_view.py, along with their dependencies (Flask, flask-cors, beautifulsoup4, trafilatura, markdownify, etc.)
- Google Cloud & API Credentials:
- Support interaction with Google’s Custom Search API.
- Supporting Scripts and Commands:
- Helper scripts like start-all-servers.cmd and start-python-servers.cmd demonstrate the orchestration of the servers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Client Applications"]:::client
    A -->|"sendsRequest"| B["MCP Server (Node.js/TypeScript)"]:::node
    B -->|"delegatesTask"| C["API & Content Analysis Server (Python/Flask)"]:::python
    C -->|"returnsResult"| B

    subgraph "Python Endpoints"
        C1["Google Search Endpoint"]:::python
        C2["Link View Endpoint"]:::python
    end
    C --> C1
    C --> C2

    D["API Credentials Management"]:::config
    D --> B
    D --> C

    E["Build & Deployment"]:::build
    E1["Build Config (tsconfig.json)"]:::build
    E2["Startup Script"]:::build
    E --> E1
    E --> E2
    E1 --> B
    E1 --> C
    E2 --> B
    E2 --> C

    click B "https://github.com/mixelpixx/google-search-mcp-server/tree/main/src/"
    click E1 "https://github.com/mixelpixx/google-search-mcp-server/blob/main/tsconfig.json"
    click C1 "https://github.com/mixelpixx/google-search-mcp-server/blob/main/google_search.py"
    click C2 "https://github.com/mixelpixx/google-search-mcp-server/blob/main/link_view.py"
    click D "https://github.com/mixelpixx/google-search-mcp-server/blob/main/api-keys.json"
    click E2 "https://github.com/mixelpixx/google-search-mcp-server/blob/main/start-all-servers.cmd"

    classDef client fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef node fill:#C1E1C1,stroke:#333,stroke-width:2px;
    classDef python fill:#F9D1D1,stroke:#333,stroke-width:2px;
    classDef config fill:#FFF59D,stroke:#333,stroke-width:2px;
    classDef build fill:#D1C4E9,stroke:#333,stroke-width:2px;
```
