# Directory Structure
```
├── .auto-committer
│ └── config.yaml
├── .gitignore
├── .npmignore
├── .vscode
│ └── tasks.json
├── build
│ ├── index.d.ts
│ ├── index.js
│ └── index.js.map
├── Dockerfile
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── smithery.yaml
├── src
│ └── index.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
```
# Source files
src/
# Config files
tsconfig.json
.env
.env.*
*.log
# Node modules (should not be included)
node_modules/
# OS / Editor specific
.DS_Store
*.pem
*.tgz
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
.pnpm-debug.log*
# Diagnostic reports (https://nodejs.org/api/report.html)
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
# Runtime data
pids
*.pid
*.seed
*.pid.lock
# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov
# Coverage directory used by tools like istanbul
coverage
*.lcov
# nyc test coverage
.nyc_output
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
.grunt
# Bower dependency directory (https://bower.io/)
bower_components
# node-waf configuration
.lock-wscript
# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release
# Dependency directories
node_modules/
jspm_packages/
# Snowpack dependency directory (https://snowpack.dev/)
web_modules/
# TypeScript cache
*.tsbuildinfo
# Optional npm cache directory
.npm
# Optional eslint cache
.eslintcache
# Optional stylelint cache
.stylelintcache
# Microbundle cache
.rpt2_cache/
.rts2_cache_cjs/
.rts2_cache_es/
.rts2_cache_umd/
# Optional REPL history
.node_repl_history
# Output of 'npm pack'
*.tgz
# Yarn Integrity file
.yarn-integrity
# dotenv environment variable files
.env
.env.development.local
.env.test.local
.env.production.local
.env.local
# parcel-bundler cache (https://parceljs.org/)
.cache
.parcel-cache
# Next.js build output
.next
out
# Nuxt.js build / generate output
.nuxt
dist
# Gatsby files
.cache/
# Comment in the public line in if your project uses Gatsby and not Next.js
# https://nextjs.org/blog/next-9-1#public-directory-support
# public
# vuepress build output
.vuepress/dist
# vuepress v2.x temp and cache directory
.temp
.cache
# vitepress build output
**/.vitepress/dist
# vitepress cache directory
**/.vitepress/cache
# Docusaurus cache and generated files
.docusaurus
# Serverless directories
.serverless/
# FuseBox cache
.fusebox/
# DynamoDB Local files
.dynamodb/
# TernJS port file
.tern-port
# Stores VSCode versions used for testing VSCode extensions
.vscode-test
# yarn v2
.yarn/cache
.yarn/unplugged
.yarn/build-state.yml
.yarn/install-state.gz
.pnp.*
# Auto Committer environment file
.auto-committer/.env
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
[](https://mseep.ai/app/kunihiros-google-patents-mcp)
# Google Patents MCP Server (`google-patents-mcp`)
[](https://smithery.ai/server/@KunihiroS/google-patents-mcp)
[](https://badge.fury.io/js/%40kunihiros%2Fgoogle-patents-mcp)
This project provides a Model Context Protocol (MCP) server that allows searching Google Patents information via the [SerpApi Google Patents API](https://serpapi.com/google-patents-api).
### Installing via Smithery
To install Google Patents MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@KunihiroS/google-patents-mcp):
```bash
npx -y @smithery/cli install @KunihiroS/google-patents-mcp --client claude
```
## Changelog
### v0.2.0 (2025-04-17)
* **Fix:** Implemented empty handlers for `resources/list` and `prompts/list` MCP methods.
* **Fix:** Declared `prompts` capability in server initialization.
* **Chore:** Updated dependencies.
These changes aim to improve compatibility with MCP clients like Claude Desktop which may require these standard endpoints, though direct testing with Claude Desktop has not yet been performed.
## Features
* Provides an MCP tool `search_patents` to search Google Patents.
* Uses SerpApi as the backend.
* Can be run directly using `npx` without local installation.
## Prerequisites
* **Node.js:** Version 18 or higher is recommended.
* **npm:** Required to run the `npx` command.
* **SerpApi API Key:** You need a valid API key from [SerpApi](https://serpapi.com/) to use the Google Patents API.
## Quick Start (Using npx)
The easiest way to run this server is using `npx`. This command downloads (if necessary) and runs the server directly.
```bash
npx @kunihiros/google-patents-mcp
```
**Note:** Replace `@kunihiros/google-patents-mcp` with the actual published package name if it differs.
The server will start and listen for MCP requests on standard input/output.
## Configuration
The server requires your SerpApi API key. You can provide it in one of the following ways:
1. **Environment Variable (Recommended for MCP Hosts):**
Set the `SERPAPI_API_KEY` environment variable when running the server. MCP Host configurations often allow setting environment variables for servers.
Example MCP Host configuration snippet (`config.json` or similar):
```json
{
"mcpServers": {
"google-patents-mcp": {
"command": "npx",
"args": [
"-y", // Skips confirmation if the package isn't installed locally
"@kunihiros/google-patents-mcp" // Use the correct package name
],
"env": {
"SERPAPI_API_KEY": "YOUR_ACTUAL_SERPAPI_KEY"
// Optional: Set log level
// "LOG_LEVEL": "debug"
}
}
}
}
```
2. **.env File:**
Create a `.env` file in the directory where you run the `npx` command (for local testing or if not using an MCP Host), or in your home directory (`~/.google-patents-mcp.env`), with the following content:
```dotenv
SERPAPI_API_KEY=YOUR_ACTUAL_SERPAPI_KEY
# Optional: Set log level (e.g., debug, info, warn, error)
# LOG_LEVEL=debug
```
**Note:** While using a `.env` file is convenient for local testing, for production or integration with MCP Hosts, setting the environment variable directly via the host configuration is the recommended and more secure approach. The primary intended use case is execution via `npx`, where environment variables are typically managed by the calling process or MCP Host.
The server searches for `.env` files in the following order:
* `./.env` (relative to where `npx` is run)
* `~/.google-patents-mcp.env` (in your home directory)
## Provided MCP Tool
### `search_patents`
Searches Google Patents via SerpApi.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "Search query (required). Although optional in SerpApi docs, a non-empty query is practically needed. Use semicolon (;) to separate multiple terms. Advanced syntax like '(Coffee) OR (Tea);(A47J)' is supported. See 'About Google Patents' for details."
},
"page": {
"type": "integer",
"description": "Page number for pagination (default: 1).",
"default": 1
},
"num": {
"type": "integer",
"description": "Number of results per page (default: 10). **IMPORTANT: Must be 10 or greater (up to 100).**",
"default": 10,
"minimum": 10,
"maximum": 100
},
"sort": {
"type": "string",
"enum": ["relevance", "new", "old"],
"description": "Sorting method. 'relevance' (default), 'new' (newest by filing/publication date), 'old' (oldest by filing/publication date).",
"default": "relevance"
},
"before": {
"type": "string",
"description": "Maximum date filter (e.g., 'publication:20231231', 'filing:20220101'). Format: type:YYYYMMDD where type is 'priority', 'filing', or 'publication'."
},
"after": {
"type": "string",
"description": "Minimum date filter (e.g., 'publication:20230101', 'filing:20220601'). Format: type:YYYYMMDD where type is 'priority', 'filing', or 'publication'."
},
"inventor": {
"type": "string",
"description": "Filter by inventor names. Separate multiple names with a comma (,)."
},
"assignee": {
"type": "string",
"description": "Filter by assignee names. Separate multiple names with a comma (,)."
},
"country": {
"type": "string",
"description": "Filter by country codes (e.g., 'US', 'WO,JP'). Separate multiple codes with a comma (,)."
},
"language": {
"type": "string",
"description": "Filter by language (e.g., 'ENGLISH', 'JAPANESE,GERMAN'). Separate multiple languages with a comma (,). Supported: ENGLISH, GERMAN, CHINESE, FRENCH, SPANISH, ARABIC, JAPANESE, KOREAN, PORTUGUESE, RUSSIAN, ITALIAN, DUTCH, SWEDISH, FINNISH, NORWEGIAN, DANISH."
},
"status": {
"type": "string",
"enum": ["GRANT", "APPLICATION"],
"description": "Filter by patent status: 'GRANT' or 'APPLICATION'."
},
"type": {
"type": "string",
"enum": ["PATENT", "DESIGN"],
"description": "Filter by patent type: 'PATENT' or 'DESIGN'."
},
"scholar": {
"type": "boolean",
"description": "Include Google Scholar results (default: false).",
"default": false
}
},
"required": ["q"]
}
```
**Output:**
Returns a JSON object containing the search results from SerpApi. The structure follows the SerpApi response format.
**Example Usage (MCP Request):**
```json
{
"mcp_version": "1.0",
"type": "CallToolRequest",
"id": "req-123",
"server_name": "google-patents-mcp",
"params": {
"name": "search_patents",
"arguments": {
"q": "organic light emitting diode",
"num": 10,
"language": "ENGLISH",
"status": "GRANT",
"after": "publication:20230101"
}
}
}
```
## Development
1. **Clone the repository (if needed for development):**
```bash
# git clone <repository-url>
# cd google-patents-mcp
```
2. **Install dependencies:**
```bash
npm install
```
3. **Create `.env` file:**
Copy `.env.example` to `.env` and add your `SERPAPI_API_KEY`.
4. **Build:**
```bash
npm run build
```
5. **Run locally:**
```bash
npm start
```
Or for development with auto-rebuild:
```bash
npm run dev
```
## Logging
* Logs are output to standard error.
* Log level can be controlled via the `LOG_LEVEL` environment variable (`error`, `warn`, `info`, `http`, `verbose`, `debug`, `silly`). Defaults to `info`.
* A log file is attempted to be created in the project root (`google-patents-server.log`), user's home directory (`~/.google-patents-server.log`), or `/tmp/google-patents-server.log`.
## License
MIT License (See LICENSE file)
```
--------------------------------------------------------------------------------
/.auto-committer/config.yaml:
--------------------------------------------------------------------------------
```yaml
# Auto Committer Configuration File
commitIntervalSeconds: 180
llm:
provider: openai
model: gpt-4o-mini
commitPrefix: '[Auto commit]'
autoPush: true
```
--------------------------------------------------------------------------------
/.vscode/tasks.json:
--------------------------------------------------------------------------------
```json
{
"version": "2.0.0",
"tasks": [
{
"label": "Start Auto Committer",
"type": "shell",
"command": "node \"/home/kunihiros/.nvm/versions/node/v22.14.0/bin/auto-committer\" start",
"isBackground": true,
"problemMatcher": [],
"presentation": {
"reveal": "silent",
"panel": "dedicated",
"showReuseMessage": false,
"clear": true
},
"runOptions": {
"runOn": "folderOpen"
}
}
]
}
```
--------------------------------------------------------------------------------
/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
startCommand:
type: stdio
configSchema:
# JSON Schema defining the configuration options for the MCP.
type: object
required:
- serpapiApiKey
properties:
serpapiApiKey:
type: string
description: SerpApi API key for authenticating requests
description: Configuration for Google Patents MCP Server
commandFunction:
# A JS function that produces the CLI command based on the given config to start the MCP on stdio.
|-
(config) => ({
command: 'node',
args: ['build/index.js'],
env: { SERPAPI_API_KEY: config.serpapiApiKey }
})
exampleConfig:
serpapiApiKey: YOUR_SERPAPI_API_KEY_HERE
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
# Stage 1: Build the TypeScript source
FROM node:lts-alpine AS builder
WORKDIR /app
# Install dependencies
COPY package*.json tsconfig.json ./
RUN npm install
# Copy source and build
COPY src ./src
RUN npm run build
# Ensure non-root ownership and set non-root user for builder stage
RUN chown -R node:node /app
USER node
# Stage 2: Create production image
FROM node:lts-alpine
WORKDIR /app
# Install only production dependencies
COPY package*.json ./
RUN npm install --only=production
# Copy built artifacts
COPY --from=builder /app/build ./build
# Ensure non-root ownership of app files
RUN chown -R node:node /app
# Expose stdio for MCP communication
# Start the MCP server
USER node
CMD ["node", "build/index.js"]
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "@kunihiros/google-patents-mcp",
"version": "0.2.0",
"description": "MCP server for searching Google Patents via SerpApi",
"main": "build/index.js",
"type": "module",
"bin": {
"google-patents-mcp": "build/index.js"
},
"scripts": {
"build": "tsc",
"start": "node build/index.js",
"dev": "tsc -w & node --watch build/index.js",
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [
"mcp",
"serpapi",
"google patents"
],
"author": "Kunihiro Sasayama",
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/KunihiroS/google-patents-mcp.git"
},
"homepage": "https://github.com/KunihiroS/google-patents-mcp#readme",
"bugs": {
"url": "https://github.com/KunihiroS/google-patents-mcp/issues"
},
"files": [
"build",
"README.md",
"LICENSE",
"package.json"
],
"dependencies": {
"@modelcontextprotocol/sdk": "^1.8.0",
"node-fetch": "^3.3.2",
"dotenv": "^16.4.5",
"winston": "^3.13.0"
},
"devDependencies": {
"@types/node": "^20.14.2",
"typescript": "^5.4.5",
"@types/node-fetch": "^2.6.11"
}
}
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2022", /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', 'ES2021', 'ES2022', or 'ESNEXT'. */
"module": "NodeNext", /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */
"outDir": "./build", /* Redirect output structure to the directory. */
"rootDir": "./src", /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
"strict": true, /* Enable all strict type-checking options. */
"esModuleInterop": true, /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
"skipLibCheck": true, /* Skip type checking of declaration files. */
"forceConsistentCasingInFileNames": true, /* Disallow inconsistently-cased references to the same file. */
"moduleResolution": "NodeNext", /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
"resolveJsonModule": true, /* Include modules imported with '.json' extension */
"declaration": true, /* Generates corresponding '.d.ts' file. */
"sourceMap": true /* Generates corresponding '.map' file. */
},
"include": ["src/**/*"], /* Specifies the files to include in the program. */
"exclude": ["node_modules", "**/*.spec.ts"] /* Specifies the files to exclude from the program. */
}
```