Trademark MCP Server

A Model Context Protocol (MCP) server that provides tools for searching and retrieving USPTO trademark information using the TSDR API.

Without database (look up specific trademarks):

export USPTO_API_KEY=your_key
npx trademark-mcp-server

With database (search by wordmark/name):

cd scripts && ./setup.sh  # Interactive wizard

This MCP server provides the following tools:

• trademark_search_by_wordmark: Search trademarks by text/name (requires local database)
• trademark_search_by_serial: Search by 8-digit serial number
• trademark_search_by_registration: Search by 7-8 digit registration number
• trademark_status: Get comprehensive status information (HTML format)
• trademark_image: Retrieve trademark image URLs
• trademark_documents: Get document bundle URLs

This server can run in two modes:

• Requirements: USPTO API key only
• Tools available: All tools EXCEPT trademark_search_by_wordmark
• Use case: Look up specific trademarks by serial/registration number

• Requirements: USPTO API key + PostgreSQL database with USPTO bulk data
• Tools available: ALL tools including trademark_search_by_wordmark
• Use case: Search trademarks by name/text, find similar marks

The server automatically detects which mode to use based on whether TRADEMARK_DB_URL is set.

pnpm install
pnpm build

Important: The USPTO TSDR API requires an API key since October 2020. You must:

1. Register at USPTO Open Data Portal
2. Get your API key from your account dashboard
3. Set environment variable: USPTO_API_KEY=your_api_key_here

Without an API key, all requests will return 401 Unauthorized errors.

You can run the server directly using npx without installing:

# Set your API key first
export USPTO_API_KEY=your_api_key_here

# Then run the server
npx trademark-mcp-server

This will start the MCP server in stdio mode, ready to receive MCP protocol messages.

If you have the package installed locally:

pnpm start
# or directly
node dist/bin.js

A convenience shell script is provided:

./start-mcp-server.sh

# Set your API key first
export USPTO_API_KEY=your_api_key_here

# Start HTTP server (default port 3000)
pnpm serve
# or directly
node dist/server.js

# Or specify a custom port
PORT=8080 pnpm serve

The HTTP server provides:

• Health check: http://localhost:3000/health
• MCP endpoint: http://localhost:3000/mcp

# Build the image
docker build -t trademark-mcp-server .

# Run the container
docker run -d \
  --name trademark-mcp-server \
  -p 3000:3000 \
  -e USPTO_API_KEY=your_api_key_here \
  trademark-mcp-server

# View logs
docker logs trademark-mcp-server

# Health check
curl http://localhost:3000/health

• Base Image: node:18-alpine (lightweight Linux distribution)
• Multi-architecture: Supports both linux/amd64 and linux/arm64
• Security: Runs as non-root user (trademark:nodejs)
• Health Checks: Built-in health monitoring on /health
• Production Ready: Optimized for production deployments

For wordmark (text) searches, you can set up a local PostgreSQL database with USPTO bulk trademark data. This enables the trademark_search_by_wordmark tool for fuzzy text searches across 13+ million trademark records.

cd scripts/
./setup.sh

The interactive wizard will guide you through:

1. USPTO API Key - Get one at data.uspto.gov
2. Database Setup - Use Docker (recommended) or an existing PostgreSQL
3. Data Selection - Choose what to import:
   • Daily updates only (recent filings)
   • Annual archive (1884-present, ~9 GB)
   • Full setup (archive + daily updates, recommended)

• PostgreSQL 15 with pg_trgm extension for fuzzy matching
• 13+ million trademark records from USPTO bulk data
• Automatic indexing for fast wordmark searches

# Interactive mode (default)
./setup.sh

# Non-interactive with pre-configured options
./setup.sh --api-key YOUR_KEY --db-url postgresql://user:pass@host:5432/db

# Test mode (single file, no prompts)
./setup.sh --test

If you prefer manual setup:

# 1. Start PostgreSQL (or use existing)
docker compose -f scripts/docker-compose.db.yml up -d

# 2. Create virtual environment
cd scripts/
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3. Initialize schema and load data
python load_xml.py --init-db --db-url postgresql://trademark:trademark@localhost:5432/trademarks
python load_xml.py --xml-paths /path/to/apc250121.zip --db-url postgresql://...

After setup, your .env file will contain:

USPTO_API_KEY=your_api_key
TRADEMARK_DB_URL=postgresql://trademark:trademark@localhost:5432/trademarks

To update with the latest daily files:

cd scripts/
./setup.sh  # Choose "Daily updates only"

The wizard detects existing data and only downloads new files.

# Set your API key first
export USPTO_API_KEY=your_api_key_here

# Run in development mode with file watching
pnpm serve:dev

# Run with MCP Inspector for debugging and testing
pnpm inspect
# or use the convenience script
./inspect-server.sh

# Run tests
pnpm test

# Lint and format
pnpm lint
pnpm format

The MCP Inspector provides a web-based interface for testing MCP servers:

# Start the inspector (opens browser at http://localhost:5173)
pnpm inspect

# Or use the standalone script
./inspect-server.sh

The inspector allows you to:

• Test all tools interactively through a web UI
• View server capabilities and available tools
• Send requests and see responses in real-time
• Debug issues with detailed logging
• Validate MCP protocol compliance

This server uses the USPTO TSDR (Trademark Status & Document Retrieval) API:

• Base URL: https://tsdrapi.uspto.gov/ts/cd
• Status Info (JSON): /casestatus/sn[SERIAL]/info.json or /casestatus/rn[REGISTRATION]/info.json
• Status Info (HTML): /casestatus/sn[SERIAL]/content.html
• Trademark Images: /rawImage/[SERIAL]
• Document Bundles: /casedocs/bundle.pdf?sn=[SERIAL]

1. Visit USPTO Open Data Portal
2. Create an account or log in
3. Navigate to your account dashboard
4. Generate a new API key for TSDR access
5. Copy your API key for use with this server

For questions about API keys, contact: APIhelp@uspto.gov

• General API calls: 60 requests per minute per API key
• PDF/ZIP downloads: 4 requests per minute per API key

You can test these examples using the MCP Inspector (pnpm inspect) or by calling the tools directly.

// Example serial number: 78787878
{
  "name": "trademark_search_by_serial",
  "arguments": {
    "serialNumber": "78787878"
  }
}

// Example registration number: 1234567
{
  "name": "trademark_search_by_registration", 
  "arguments": {
    "registrationNumber": "1234567"
  }
}

{
  "name": "trademark_image",
  "arguments": {
    "serialNumber": "78787878"
  }
}

Try these working examples in the MCP Inspector:

• Apple trademark: Serial number 78462704
• Nike trademark: Serial number 72016902
• Microsoft trademark: Serial number 78213220

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "trademark-mcp-server": {
      "command": "npx",
      "args": ["trademark-mcp-server"],
      "env": {
        "USPTO_API_KEY": "your_api_key_here"
      }
    }
  }
}

If you have the package installed locally:

{
  "mcpServers": {
    "trademark-mcp-server": {
      "command": "node",
      "args": ["/path/to/trademark-mcp-server/dist/bin.js"],
      "env": {
        "USPTO_API_KEY": "your_api_key_here"
      }
    }
  }
}

You can also use the provided shell script:

{
  "mcpServers": {
    "trademark-mcp-server": {
      "command": "/path/to/trademark-mcp-server/start-mcp-server.sh",
      "env": {
        "USPTO_API_KEY": "your_api_key_here"
      }
    }
  }
}

MIT

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting: pnpm test && pnpm lint
5. Submit a pull request

For more information about the USPTO TSDR API, visit:

• USPTO Open Data Portal
• TSDR API Documentation