Google Home MCP Server

A Model Context Protocol (MCP) server that provides tools to download and query the Google Home API knowledge base.

Features

• Download Tool: Downloads the Google Home API knowledge base from GitHub
• Query Tool: Provides the knowledge base content to AI clients for intelligent querying
• Type-Safe: Built with TypeScript and Zod validation
• Error Handling: Comprehensive error messages returned to MCP clients

Installation

From npm (Recommended)

npm install -g google-home-mcp-server

From source (Development)

git clone https://github.com/timhuang1018/google-home-mcp-p1.git
cd google-home-mcp-p1
npm install
npm run build

Updating

For npx users (recommended)

Using google-home-mcp-server@latest automatically fetches the latest version each time the server starts.

For global installation users

npm update -g google-home-mcp-server

Development

npm run dev

Available Tools

1. download_google_home_knowledge

Downloads the Google Home API knowledge base file from GitHub and saves it locally.

Parameters: None

Example:

Tool: download_google_home_knowledge

2. query_google_home_api

Queries the Google Home API knowledge base. Returns the file path to the knowledge base so the AI can use the Read tool to access relevant content as needed. This token-efficient approach allows the AI to selectively read sections as needed.

Parameters:

• query_text (required): Your question about the Google Home API

Example:

Tool: query_google_home_api
Arguments: { "query_text": "How do I authenticate with Google Home API?" }

Note: The knowledge base file must be downloaded first using download_google_home_knowledge.

Usage with MCP Clients

Claude Code

Add to your ~/.config/claude-code/claude_code_config.json:

{
  "mcpServers": {
    "google-home": {
      "command": "npx",
      "args": ["-y", "google-home-mcp-server@latest"]
    }
  }
}

Gemini CLI

Add to your MCP configuration:

{
  "mcpServers": {
    "google-home": {
      "command": "npx",
      "args": ["-y", "google-home-mcp-server@latest"]
    }
  }
}

Alternative: Global Installation

If you installed globally with npm install -g google-home-mcp-server:

{
  "mcpServers": {
    "google-home": {
      "command": "google-home-mcp-server"
    }
  }
}

Important:

• Add mcp/ to your .gitignore in your workspace to exclude the downloaded knowledge base from version control.
• Using @latest ensures you always get the most recent version when the MCP server starts.

Development Mode (from source)

For local development from source:

{
  "mcpServers": {
    "google-home": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/google-home-mcp-p1/src/index.ts"]
    }
  }
}

Testing with MCP Inspector

npx @modelcontextprotocol/inspector npx -y google-home-mcp-server@latest

This will open a web interface where you can:

• View available tools
• Test tool calls with arguments
• Inspect request/response payloads
• Debug error messages

Project Structure

google-home-mcp-p1/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── handlers/
│   │   ├── index.ts          # Tool registration and routing
│   │   ├── download.ts       # Download tool handler
│   │   └── query.ts          # Query tool handler
│   ├── schemas/
│   │   └── tools.ts          # Zod validation schemas
│   └── config/
│       └── constants.ts      # Configuration constants
├── build/                    # Compiled JavaScript (gitignored)
├── mcp/                      # Downloaded knowledge base (gitignored)
│   └── google-home/
│       └── google-home-api-knowledge-base.txt
├── doc/
│   └── google-home-mcp-feature.md
├── package.json
├── tsconfig.json
└── README.md

Architecture

• Transport: stdio (standard input/output)
• Protocol: MCP (Model Context Protocol) using JSON-RPC 2.0
• SDK: Official @modelcontextprotocol/sdk v1.0.4
• Validation: Zod schemas for type-safe argument validation
• Error Handling: Application-level errors (isError: true) returned to client

Error Handling

All errors are returned to the MCP client with descriptive messages:

• Network failures during download
• File not found errors
• Invalid arguments
• Permission errors

The AI client (Claude Code, Gemini CLI, etc.) can see these errors and handle them appropriately.

Query Strategy

The query_google_home_api tool uses a token-efficient approach by returning the file path to the knowledge base instead of the full content. This allows the AI client to:

• Use the Read tool to selectively access relevant sections
• Minimize token consumption
• Understand context and semantics as needed
• Provide accurate, contextualized answers
• Handle follow-up questions naturally without re-sending entire content

Requirements

• Node.js v18 or higher
• npm or yarn

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Run server in development mode with tsx
• npm start - Run compiled server

License

ISC