Skip to main content
Glama
j-platpat-mcp
by yamayued

j-platpat-mcp

j-platpat-mcp is a public MCP server scaffold for the official JPO patent information acquisition API (特許情報取得API).

This repository intentionally wraps the official API layer and does not scrape the J-PlatPat web UI. It also does not use unofficial Google Patents scraping or fallback endpoints.

What This Repo Is

  • A stdio MCP server for local MCP clients such as Codex, Claude Desktop, Cline, and similar tools.

  • A retrieval-oriented wrapper around the official JPO endpoints for patent, trademark, and selected shared utilities.

  • A starting point for an internal-first architecture where search is handled by a separate bulk-data index.

Related MCP server: houjin-bangou-api-mcp

What This Repo Is Not

  • Not a J-PlatPat browser automation project.

  • Not a full-text patent search engine.

  • Not a Google Patents scraper or metadata enrichment proxy.

  • Not a substitute for reading and complying with the JPO / INPIT terms of use.

Why This Shape

The official API is strongest when you already know a case number, applicant, or document family you want to retrieve. It is not a drop-in replacement for J-PlatPat's interactive UI search.

That makes a practical architecture look like this:

  1. Use the official JPO API as the evidence-grade retrieval layer.

  2. Add a separate internal search/index layer later for natural-language or broader discovery workflows.

This repository implements step 1 cleanly so step 2 can be added later without throwing away the MCP interface.

For a direct map of MCP tools to wrapped JPO endpoints, see docs/tool-coverage.md. For contribution and maintenance guidance, see CONTRIBUTING.md and docs/repository-settings.md.

Included Tools

The current scaffold exposes these MCP tools:

  • lookup_number_relation

  • get_patent_progress

  • get_patent_progress_simple

  • get_patent_citations

  • get_patent_documents

  • get_patent_registration

  • get_patent_divisional_app_info

  • get_patent_family

  • get_patent_family_list

  • get_patent_global_cite_class

  • get_patent_global_doc_list

  • get_patent_global_document

  • get_patent_jp_document

  • get_patent_pct_national_phase_application_number

  • get_patent_priority_right_app_info

  • get_design_progress

  • get_design_progress_simple

  • get_design_registration

  • get_design_documents

  • get_design_priority_right_app_info

  • get_trademark_progress

  • get_trademark_progress_simple

  • get_trademark_registration

  • get_trademark_documents

  • get_trademark_priority_right_app_info

  • resolve_applicant_code

  • get_jplatpat_permalink

The document tools map the official split endpoints into one MCP tool with a documentKind switch:

  • opinion_amendment

  • refusal_reason

  • refusal_reason_decision

Features

  • Password grant and refresh-token grant support against https://ip-data.jpo.go.jp/auth/token

  • Automatic bearer token handling

  • In-memory cache for repeated reads

  • Simple minimum-interval throttling per process

  • Mock smoke test for auth / retry / cache behavior without live JPO credentials

  • TypeScript + current MCP TypeScript SDK scaffold

Practical Use Cases

This server is most useful after a person has already identified a target case and wants to retrieve official records quickly.

  • Patent or trademark teams checking prosecution progress for a known application number

  • Attorney or paralegal workflows that need registration details and official document bundles

  • Internal tools that want a stable J-PlatPat permalink for case handoff or record review

  • Applicant-name or applicant-code resolution before pulling detailed case data

In other words, this repository is realistic as a retrieval MCP for known cases. It is not yet a replacement for exploratory prior-art search or similar-mark search.

Requirements

  • Node.js 20+

  • A registered JPO API account

  • JPO-issued ID and password

Official registration and documents:

利用申請

この MCP は J-PlatPat の画面をスクレイピングせず、特許庁の公式 特許情報取得API を使います。

利用には、特許庁から発行される ID / パスワードが必要です。2026年3月11日時点では、特許庁の案内ページにある利用申込書を記入し、PA0630@jpo.go.jp へメール送付して申請します。

申請案内:

技術資料:

認証まわりの要点:

  • トークン取得先は https://ip-data.jpo.go.jp/auth/token

  • grant_type=password でアクセストークン取得

  • grant_type=refresh_token でアクセストークン再取得

  • アクセストークンは 1 時間

  • リフレッシュトークンは 8 時間

Setup

Install dependencies:

npm install

Copy the example environment file:

Copy-Item .env.example .env

Fill in your credentials in .env:

JPO_USERNAME=your-issued-id
JPO_PASSWORD=your-issued-password
JPO_BASE_URL=https://ip-data.jpo.go.jp
JPO_API_BASE_PATH=/api
JPO_AUTH_PATH=/auth/token
JPO_USER_AGENT=j-platpat-mcp/0.1.0
JPO_CACHE_TTL_MS=300000
JPO_MIN_INTERVAL_MS=250
JPO_REQUEST_TIMEOUT_MS=30000

Run in development:

npm run dev:local

dev:local and start:local will load .env from the repository root when present, and otherwise continue with the current process environment. The built-in .env loader accepts common UTF-8 .env files, including files with a UTF-8 BOM from Windows editors.

If credentials are not configured, the server can still start and expose tool metadata, but JPO-backed tool calls will return a clear configuration error instead of failing during startup. Invalid JPO_BASE_URL, JPO_API_BASE_PATH, or JPO_AUTH_PATH values now fail fast during startup with a configuration message.

Build for production:

npm run build

Run the mock smoke test without real JPO credentials:

npm run test:mock

Run an MCP-level smoke test that validates tool registration and publication-number normalization without real JPO credentials:

npm run test:mcp

Run a smoke test that verifies the server still starts without credentials and returns a deterministic configuration error on JPO API calls:

npm run test:no-credentials

Run config validation checks for URL settings and UTF-8 BOM .env handling:

npm run test:config

Run non-JSON response checks for auth/API endpoints:

npm run test:non-json

Run endpoint parity check against api_reference.js:

npm run check:coverage

Run parity check against both local and official api_reference.js:

npm run check:api-parity:remote

Run parity check against official reference and create a GitHub issue when drift is found:

npm run check:api-parity:remote:issue

If API coverage drift is detected and you want to automatically open a GitHub issue (when running in CI with GITHUB_TOKEN and GITHUB_REPOSITORY), run:

node scripts/check-api-parity.mjs --create-issue

In this mode, the check generates a stable drift fingerprint and skips creating a duplicate issue when an open issue with the same fingerprint already exists.

To verify the local api_reference.js against the latest official JPO guide reference:

node scripts/check-api-parity.mjs --check-remote

(--check-remote can be combined with --create-issue when run in CI with credentials.)

What this verifies today:

  • password-grant login

  • refresh-token re-authentication

  • bearer-token attachment on API calls

  • one retry after 401

  • cache hits on repeated reads

Run the built server with local .env loading:

npm run start:local

動作確認

ID / パスワード発行後は、まず .env を埋めてから起動します。

JPO_USERNAME=your-issued-id
JPO_PASSWORD=your-issued-password

最初の確認としては、MCP を経由する前に JPO API 自体へログインできるかを見るのが確実です。

PowerShell 例:

$body = @{
  grant_type = "password"
  username = "your-issued-id"
  password = "your-issued-password"
}

Invoke-RestMethod `
  -Method Post `
  -Uri "https://ip-data.jpo.go.jp/auth/token" `
  -ContentType "application/x-www-form-urlencoded" `
  -Body $body

access_token が返れば認証成功です。

その後、このリポジトリの MCP を起動します。

npm run dev:local

このサーバは次のような「番号が分かっている案件」の取得に向いています。

  • get_patent_progress

  • get_design_progress

  • get_patent_registration

  • get_design_registration

  • get_trademark_progress

  • lookup_number_relation

例えば get_patent_progress では、10桁の出願番号を渡して公式 API の patent/v1/app_progress/{出願番号} を呼びます。

利用上の注意

このリポジトリは検索 UI の代替ではありません。公式 API は取得系が中心なので、自由語検索や探索的な検索は別途インデックス層を足す前提です。

また、アクセス数は ID 単位で管理されるため、キャッシュと簡易レート制御を入れています。

MCP Client Example

Most MCP clients want explicit environment variables in their config. Example:

{
  "mcpServers": {
    "j-platpat": {
      "command": "node",
      "args": [
        "C:/path/to/j-platpat-mcp/dist/index.js"
      ],
      "env": {
        "JPO_USERNAME": "your-issued-id",
        "JPO_PASSWORD": "your-issued-password",
        "JPO_BASE_URL": "https://ip-data.jpo.go.jp",
        "JPO_API_BASE_PATH": "/api",
        "JPO_AUTH_PATH": "/auth/token",
        "JPO_USER_AGENT": "j-platpat-mcp/0.1.0",
        "JPO_CACHE_TTL_MS": "300000",
        "JPO_MIN_INTERVAL_MS": "250",
        "JPO_REQUEST_TIMEOUT_MS": "30000"
      }
    }
  }
}

Compliance Notes

  • This repository is designed around the official JPO API, not J-PlatPat screen scraping.

  • Unofficial J-PlatPat session endpoints and Google Patents scraping paths are intentionally out of scope for this server.

  • You must obtain credentials and follow the API terms and handbook.

  • Access counts are managed per ID, so cache and rate control are enabled by default.

  • resolve_applicant_code uses exact-match applicant names because that is how the official endpoint works.

If you plan to publish a third-party SaaS or multi-tenant service, review the JPO terms very carefully before doing so.

Current Limits

  • No bulk-data ingestion layer yet

  • No free-text search index yet

  • No fixture-based tests yet

  • No live verification against a JPO-issued production account in this repository

Validation Status

This repository has not yet been verified in a live production JPO API environment.

What has been validated locally:

  • npm run check

  • npm run build

  • npm run test:mock

  • npm run test:mcp

  • npm run test:no-credentials

  • npm run test:config

  • npm run test:non-json

  • npm run check:coverage

  • stdio MCP startup with and without configured JPO credentials

What still needs a real JPO account:

  • live /auth/token verification

  • response-shape confirmation against production data

  • access-count behavior under real usage

  • end-to-end checks for each wrapped endpoint

Roadmap

  • Add bulk-data ingestion for 特許情報標準データ / download service snapshots

  • Build a separate search index layer for natural-language and exploratory workflows

  • Add coverage for any remaining official endpoint families not in the public endpoint list

  • Add response fixtures and regression tests

  • Add optional Streamable HTTP transport for remote internal deployment

Publishing Checklist

  • Adjust package.json author metadata if you want a different display name

  • Update the MCP client path example for your actual install path

  • Decide whether you want MIT as-is or another license

  • Add your own issue templates, CI gates, and release process

Official References

These are the main sources this scaffold follows:

Notable confirmed details reflected in this scaffold:

  • Access tokens are obtained at /auth/token

  • Refresh uses the same /auth/token endpoint with grant_type=refresh_token

  • Access token validity is 1 hour and refresh token validity is 8 hours

  • The official notice dated 2026-03-02 states domestic API access limits were relaxed

License

MIT

Developer / 開発・運営元

Available Tools

27 tools
get_design_documentsGet Design DocumentsB
Read-only

Fetch design application document bundles such as amendment, refusal reason, and decision packages.

Inputs: documentKind (required), applicationNumber (required).

get_design_priority_right_app_infoGet Design Priority Right InformationC
Read-only

Fetch design priority-right information.

Inputs: applicationNumber (required).

get_design_progressGet Design ProgressC
Read-only

Fetch design prosecution progress from the official JPO API.

Inputs: applicationNumber (required).

get_design_progress_simpleGet Design Progress (Simple)B
Read-only

Fetch compact design prosecution progress from the official JPO API.

Inputs: applicationNumber (required).

get_design_registrationGet Design RegistrationB
Read-only

Fetch design registration information from the official JPO API.

Inputs: applicationNumber (required).

get_patent_citationsGet Patent CitationsC
Read-only

Fetch cited document information for a patent application from the official JPO API.

Inputs: applicationNumber (required).

get_patent_divisional_app_infoGet Patent Divisional Application InformationC
Read-only

Fetch patent divisional-application information.

Inputs: applicationNumber (required).

get_patent_documentsGet Patent DocumentsC
Read-only

Fetch patent application document bundles such as amendment, refusal reason, and decision packages.

Inputs: documentKind (required), applicationNumber (required).

get_patent_familyGet Patent FamilyB
Read-only

Fetch patent family record by case number.

Inputs: relation (required), caseNumber (required).

get_patent_family_listGet Patent Family ListC
Read-only

Fetch patent family list by case number.

Inputs: relation (required), caseNumber (required).

get_patent_global_cite_classGet Patent Global Citation ClassC
Read-only

Fetch patent global citation class information.

Inputs: applicationNumber (required).

get_patent_global_doc_listGet Patent Global Document ListC
Read-only

Fetch patent global document list.

Inputs: applicationNumber (required).

get_patent_global_documentGet Patent Global DocumentC
Read-only

Fetch one patent global document by document ID.

Inputs: documentId (required), applicationNumber (required).

get_patent_jp_documentGet Patent Japan DocumentC
Read-only

Fetch one patent Japan document by document ID.

Inputs: documentId (required), applicationNumber (required).

get_patent_pct_national_phase_application_numberGet Patent PCT National Phase NumberC
Read-only

Resolve PCT national phase application number.

Inputs: relation (required), caseNumber (required).

get_patent_priority_right_app_infoGet Patent Priority Right InformationC
Read-only

Fetch patent priority-right information.

Inputs: applicationNumber (required).

get_patent_progressGet Patent ProgressB
Read-only

Fetch patent prosecution progress from the official JPO API.

Inputs: applicationNumber (required).

get_patent_progress_simpleGet Patent Progress (Simple)B
Read-only

Fetch compact patent prosecution progress from the official JPO API.

Inputs: applicationNumber (required).

get_patent_registrationGet Patent RegistrationB
Read-only

Fetch patent registration information from the official JPO API.

Inputs: applicationNumber (required).

get_trademark_documentsGet Trademark DocumentsB
Read-only

Fetch trademark application document bundles such as amendment, refusal reason, and decision packages.

Inputs: documentKind (required), applicationNumber (required).

get_trademark_priority_right_app_infoGet Trademark Priority Right InformationC
Read-only

Fetch trademark priority-right information.

Inputs: applicationNumber (required).

get_trademark_progressGet Trademark ProgressC
Read-only

Fetch trademark prosecution progress from the official JPO API.

Inputs: applicationNumber (required).

get_trademark_progress_simpleGet Trademark Progress (Simple)B
Read-only

Fetch compact trademark prosecution progress from the official JPO API.

Inputs: applicationNumber (required).

get_trademark_registrationGet Trademark RegistrationB
Read-only

Fetch trademark registration information from the official JPO API.

Inputs: applicationNumber (required).

lookup_number_relationLookup Number RelationC
Read-only

Resolve official case number relationships from the JPO case number reference API.

Inputs: domain (required), caseNumber (required), relationType (required).

resolve_applicant_codeResolve Applicant CodeA
Read-only

Resolve applicant code to name or name to applicant code using the official JPO applicant endpoints.

Inputs: value (required), domain (required), lookupBy (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 27 tools

    Disambiguation4/5

    Tools are mostly separated by domain (patent/design/trademark) and resource type, making most purposes distinct. However, near-duplicate pairs like get_patent_progress vs get_patent_progress_simple and get_patent_family vs get_patent_family_list create some potential for misselection.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern: get_*, resolve_*, and lookup_* with domain/resource prefixes. Minor noun abbreviations such as doc vs document and app_info are used consistently within families and do not break predictability.

    Tool Count2/5

    With 27 tools, the server exceeds the 25-tool threshold for 'too many' in the rubric. Although the breadth reflects three domains, the set is heavy and includes near-duplicate progress/simple variants that could be consolidated.

    Completeness4/5

    Core JPO retrieval operations across patents, designs, and trademarks are covered: registration, documents, progress, priority rights, citations, family, global/JP documents, and number resolution. Missing search/bulk discovery or some cross-domain utilities are minor gaps that agents can likely work around.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server for searching Japanese Diet bills and committee Q\&A records via the NDL Kokkai API.
      4
      42 npm
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      MCP server for the Japan National Tax Agency Corporate Number API, enabling corporate number lookup and search via local AI clients.
      3
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for searching Japanese corporate data including companies, financials, patents, subsidies, and government statistics via official government APIs.
      1
      MIT