Installing `patent-client-agents`¶

patent-client-agents covers seven install modes. Pick the one that matches how you're going to use it:

Mode	You want to...	Section
Python library	Import `patent_client_agents` in your own async code	§1
Python library + MCP runtime	Run an MCP server locally or in-process	§2
Claude Code plugin (from GitHub marketplace)	Add 63 patent MCP tools to Claude Code with two slash commands	§3
Claude Code skill (standalone, library-user)	Install the `ip_research` skill into `~/.claude/skills/` for Python-library guidance	§4
Stdio MCP (any MCP client)	Connect Claude Desktop / Cursor / Cline / CoWork-local / custom client	§5
Remote MCP (hosted or self-hosted)	Point an MCP client at a deployed HTTPS endpoint	§6

Skip to the section you need — they're independent.

The Claude Code plugin (§3) ships the MCP server only. The ip_research skill is a separate artifact aimed at Python-library users (§4); the plugin installs MCP tools whose in-schema descriptions already cover the routing/usage guidance a skill would otherwise centralize.

1. Python library¶

Use this when you're writing async Python that calls patent APIs directly — no MCP, no Claude Code. The bare install pulls no MCP-runtime dependencies (fastmcp, starlette), so it stays lean.

Install¶

pip install patent-client-agents

Or with uv:

uv add patent-client-agents

API keys¶

Set via environment variables. Most connectors work without keys but these unlock the full surface:

Variable	Source	How to get
`USPTO_ODP_API_KEY`	USPTO Open Data Portal	developer.uspto.gov (free)
`EPO_OPS_API_KEY`, `EPO_OPS_API_SECRET`	EPO Open Patent Services	developers.epo.org (free, 4 GB/week)
`JPO_API_USERNAME`, `JPO_API_PASSWORD`	JPO J-PlatPat	Contact JPO (restricted)

Google Patents, USPTO Publications, USPTO Assignments, and MPEP need no credentials.

Verify¶

import asyncio
from patent_client_agents.google_patents import GooglePatentsClient

async def main():
    async with GooglePatentsClient() as client:
        patent = await client.get_patent_data("US10123456B2")
        print(patent.title)

asyncio.run(main())

Expected output: Phase change material heat sink using additive manufacturing and method.

2. Python library with MCP runtime¶

Use this when you want to run the stdio MCP server from the same venv as other Python work — e.g. embedding ip_mcp in your own composed FastMCP server, or running patent-client-agents-mcp as a subprocess from a Python script.

Install¶

pip install 'patent-client-agents[mcp]'

The [mcp] extra pulls fastmcp>=3.2.3 and starlette>=0.37 on top of the base dependencies.

What you get¶

Two new console scripts on your PATH:

patent-client-agents-mcp — launches the stdio MCP server (63 patent tools)
patent-client-agents-skill-install — symlinks the ip_research skill into ~/.claude/skills/ (see §4)

Plus the Python-importable MCP surface:

from patent_client_agents.mcp import ip_mcp                 # pre-composed FastMCP
from patent_client_agents.mcp.server import mcp as ip_server  # + middleware + routes

Mount ip_mcp inside your own FastMCP server:

from fastmcp import FastMCP
from patent_client_agents.mcp import ip_mcp

my_server = FastMCP("my-server")
my_server.mount(ip_mcp)  # + your own tools alongside

This is exactly how law-tools consumes patent-client-agents in the monorepo.

3. Claude Code plugin (from GitHub)¶

Use this when you use Claude Code and want the 63 patent MCP tools dropped in with two slash commands.

The plugin ships only the MCP server — no skill, no agents, no hooks. The MCP tools' in-schema descriptions already carry the cross-tool routing guidance a skill would otherwise centralize (e.g. search_google_patents tells the agent "PREFER search_patent_publications for US patents"; get_epo_cql_help is itself a tool).

Prereq¶

uv needs to be on PATH. The plugin's MCP server spawns via uvx, which handles the Python runtime (fastmcp and friends) in a managed environment so you don't have to pip install anything.

# install uv if you don't have it — one-liner from astral.sh
curl -LsSf https://astral.sh/uv/install.sh | sh

Install¶

Claude Code's plugin install goes through a marketplace — a small catalog manifest that lists one or more plugins. This repo ships its own single-plugin marketplace at .claude-plugin/marketplace.json, with the plugin itself living in a subdirectory (plugins/patent-client-agents/) that the schema requires.

Run these inside a Claude Code session (slash commands, not shell):

/plugin marketplace add parkerhancock/patent-client-agents
/plugin install patent-client-agents@patent-client-agents
/reload-plugins

What happens:

/plugin marketplace add parkerhancock/patent-client-agents clones this repo into ~/.claude/plugins/marketplaces/, parses .claude-plugin/marketplace.json, and registers the marketplace under the name it declares (patent-client-agents).
/plugin install patent-client-agents@patent-client-agents resolves the patent-client-agents plugin from that marketplace (the redundant @patent-client-agents suffix is the marketplace name, not the plugin name), links it into ~/.claude/plugins/, and registers the MCP server declared in plugins/patent-client-agents/.claude-plugin/plugin.json.
/reload-plugins tells Claude Code to pick up the newly-registered plugin in the current session.
On first MCP use, uvx fetches patent-client-agents[mcp] from PyPI (not from the cloned repo — the plugin manifest uses uvx --from patent-client-agents[mcp] patent-client-agents-mcp) into a managed environment and launches the server. The first run takes ~30 seconds while ~100 packages download; subsequent runs are fast because uv caches the resolved environment.

Expected output after install + reload:

Reloaded: 1 plugin · 0 skills · … agents · 0 hooks · 1 plugin MCP server · 0 plugin LSP servers

0 skills is the intended state — see the note at the top of this doc.

Update¶

When a new plugin version lands on GitHub:

/plugin marketplace update patent-client-agents
/reload-plugins

The first command pulls the latest marketplace commit (which includes any plugin-manifest changes). /reload-plugins then re-reads the registered plugin's manifest. If the PyPI version referenced by uvx --from patent-client-agents[mcp] changed, the next MCP call rebuilds the uv-managed env.

If you need to force a clean reinstall:

/plugin uninstall patent-client-agents@patent-client-agents
/plugin install patent-client-agents@patent-client-agents
/reload-plugins

Remove¶

/plugin uninstall patent-client-agents@patent-client-agents
/plugin marketplace remove patent-client-agents

Configure API keys¶

API keys are read from environment. For a global Claude Code install, export them in your shell profile:

export USPTO_ODP_API_KEY="…"
export EPO_OPS_API_KEY="…"
export EPO_OPS_API_SECRET="…"

Restart Claude Code so the new env reaches the MCP subprocess. Without keys, Google Patents / PPUBS / MPEP / Assignments still work; USPTO ODP and EPO tools will return auth errors.

Verify¶

List MCP tools from within a Claude Code session:

/mcp

Expect patent-client-agents with 63 tools. Or call one directly by asking something patent-research-ish:

"What's in MPEP section 2106?"

Claude invokes get_mpep_section via the MCP server and returns the text of MPEP 2106 — Patent Subject Matter Eligibility.

Troubleshooting¶

uvx: command not found — install uv (see prereq).

/mcp shows the server as "failed to start" — open the logs pane and look for stderr output. Common causes: offline during first install (uvx can't reach PyPI), or an ancient macOS Python build error (upgrade uv to latest).

Cold start takes too long — subsequent runs are ~1s. If every session takes 30s, something is evicting uv's cache. Check that ~/.cache/uv/ is persistent.

Plugin shows 0 tools after install — /reload-plugins didn't pick it up. Fully exit Claude Code and restart the session.

4. Claude Code skill (standalone, library-user)¶

The Claude Code plugin (§3) intentionally ships only the MCP server — its tool descriptions carry the routing guidance a skill would centralize. This section is for a different use case: you installed patent-client-agents as a Python library (§1 or §2) and want the ip_research skill's reference docs available in Claude Code for when you're writing Python code that uses the library.

The skill covers:

Client class → import path routing
Query-syntax cheat sheets (CQL for EPO, PPUBS field codes, Lucene for USPTO OA)
Gotchas (patent number formats, JPO credentials, rate limits)
Python usage examples

Install¶

pip install 'patent-client-agents[mcp]'   # or without [mcp] if you don't need the MCP runtime
patent-client-agents-skill-install

Creates ~/.claude/skills/ip-research as a symlink into the pip-installed package. Idempotent — re-runs no-op when already linked.

Point at a different target¶

patent-client-agents-skill-install --target=/path/to/other/skills/dir

Replace an existing directory¶

patent-client-agents-skill-install --force

Backs up any existing ip-research dir to ip-research.bak and replaces with the symlink.

Plugin vs. standalone skill¶

	Plugin (§3)	Standalone skill (§4)
What it installs	MCP server only (63 tools)	Skill markdown for Python library usage
Command	`/plugin install patent-client-agents@patent-client-agents`	`patent-client-agents-skill-install`
Source	Cloned marketplace repo	pip-installed package (symlinked)
Updates	`/plugin marketplace update` + `/reload-plugins`	Reinstall `patent-client-agents` to pick up new skill content
Best for	Agents calling MCP tools	Humans writing Python that imports `patent_client_agents`

The two paths can co-exist on the same machine — the plugin provides the MCP tools to agents, the standalone skill provides reference docs to humans working in the codebase.

5. Stdio MCP from any MCP client¶

Use this when you want every patent tool available as MCP tools to your client (Claude Desktop, Cursor, Cline, CoWork-local, or a custom fastmcp client). The server is a short-lived subprocess speaking JSON-RPC over stdio.

Install¶

pip install 'patent-client-agents[mcp]'

This gives you the patent-client-agents-mcp console script on PATH.

Wire the MCP client¶

Claude Code¶

Add to .mcp.json at your project root (or ~/.claude.json for user-scope):

{
  "mcpServers": {
    "patent-client-agents": {
      "command": "patent-client-agents-mcp"
    }
  }
}

Or add from the CLI:

claude mcp add patent-client-agents patent-client-agents-mcp

If you're using a venv, point at the absolute path so Claude Code launches the right interpreter:

{
  "mcpServers": {
    "patent-client-agents": {
      "command": "/path/to/.venv/bin/patent-client-agents-mcp",
      "env": {
        "USPTO_ODP_API_KEY": "…",
        "EPO_OPS_API_KEY": "…",
        "EPO_OPS_API_SECRET": "…"
      }
    }
  }
}

Claude Desktop¶

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "patent-client-agents": {
      "command": "patent-client-agents-mcp",
      "env": {
        "USPTO_ODP_API_KEY": "…"
      }
    }
  }
}

Cursor, Cline, and other stdio MCP clients¶

Same pattern — command: "patent-client-agents-mcp" plus any env vars. Consult the client's own MCP config docs for the file location.

Verify¶

import asyncio
from fastmcp import Client
from fastmcp.client.transports import StdioTransport

async def main():
    async with Client(StdioTransport(command="patent-client-agents-mcp", args=[])) as c:
        tools = await c.list_tools()
        print(f"{len(tools)} tools")
        result = await c.call_tool("get_mpep_section", {"section": "2106"})
        print(result.data.get("title"))

asyncio.run(main())

Expect 63 tools and title starting 2106 ... Patent Subject Matter Eligibility.

Troubleshooting¶

patent-client-agents-mcp: command not found — [mcp] extra wasn't installed. Rerun pip install 'patent-client-agents[mcp]'.

ModuleNotFoundError: No module named 'fastmcp' at startup — same root cause. Something is launching a Python that doesn't have fastmcp.

Zero tools listed — the MCP client is likely talking to the wrong server. Check the JSON config points at the right binary.

6. Remote MCP¶

Use this when an MCP client (Claude Code, Claude Desktop, CoWork, Cursor, custom agent) should point at a hosted endpoint instead of spawning a local subprocess.

Public demo¶

A hosted instance runs at https://mcp.patentclient.com. Add it to any MCP client with just the URL — no tokens, no setup:

{
  "mcpServers": {
    "patent-client-agents": {
      "url": "https://mcp.patentclient.com/mcp"
    }
  }
}

The first time you connect, you'll be sent to Google sign-in. Approve, and you're done. Any verified Google account works. Usage is rate-limited per account (100 MB/day, 20 MB/minute).

This is a public demo — don't send confidential material through it. See the Terms of Use.

Deciding which path¶

  Are you writing Python that uses the library directly?
  ├── yes → §1 (bare) or §2 (with MCP runtime)
  └── no ↓

  Are you a Claude Code user?
  ├── yes → §3 (plugin install from GitHub)
  │         plus §5 if you also want the tools as MCP locally
  └── no ↓

  Are you on Claude Desktop / Cursor / Cline / other MCP client?
  ├── local subprocess → §5 (stdio MCP)
  └── pointing at a deployed server → §6 (remote MCP)

Getting help¶

Issues: github.com/parkerhancock/patent-client-agents/issues
Full source: github.com/parkerhancock/patent-client-agents
Per-source API notes: src/patent_client_agents/catalog/sources/
MCP tool reference (by intent): src/patent_client_agents/catalog/intents/

Installing patent-client-agents¶

1. Python library¶

Install¶

API keys¶

Verify¶

2. Python library with MCP runtime¶

Install¶

What you get¶

3. Claude Code plugin (from GitHub)¶

Prereq¶

Install¶

Update¶

Remove¶

Configure API keys¶

Verify¶

Troubleshooting¶

4. Claude Code skill (standalone, library-user)¶

Install¶

Point at a different target¶

Replace an existing directory¶

Plugin vs. standalone skill¶

5. Stdio MCP from any MCP client¶

Install¶

Wire the MCP client¶

Claude Code¶

Claude Desktop¶

Cursor, Cline, and other stdio MCP clients¶

Verify¶

Troubleshooting¶

6. Remote MCP¶

Public demo¶

Deciding which path¶

Getting help¶

Installing `patent-client-agents`¶