MCP KIPRIS

English | 한국어 →

An MCP (Model Context Protocol) server that gives AI assistants like Claude direct access to KIPRIS — South Korea's official patent and trademark database operated by the Korean Intellectual Property Office (KIPO).

Why KIPRIS?

South Korea is one of the top 5 patent-filing countries in the world. Companies like Samsung, LG, SK Hynix, Hyundai, and POSCO file tens of thousands of patents every year — all searchable through KIPRIS.

This MCP server lets Claude (or any MCP-compatible AI client) search those patents in natural language, without the user needing to navigate the Korean-language KIPRIS web portal.

Typical use cases:

• Prior art search before filing a patent
• Competitive intelligence on Korean technology companies
• Monitoring IPC classifications in a specific technical domain
• Trademark clearance for the Korean market

Quick Start

> Prerequisites: Python 3.11+, a free KIPRIS API key

# 1. Clone and install
git clone https://github.com/nuri428/mcp_kipris.git
cd mcp_kipris
pip install -e .

# 2. Set your API key
export KIPRIS_API_KEY="your_api_key_here"

# 3. Run the server (stdio mode for Claude Desktop)
python -m mcp_kipris.server

Then add the server to Claude Desktop — see Claude Desktop Configuration.

Getting a KIPRIS API Key

1. Go to https://plus.kipris.or.kr *(site is in Korean — use a browser translator)*

2. Register for a free account

3. Apply for an Open API key from the developer portal

4. Your key is free for non-commercial use with a daily request quota

Rate Limiting

Outgoing requests to KIPRIS are throttled by an in-process rate limiter capped at 60 requests per minute (the default in `RateLimiter`, `src/mcp_kipris/kipris/rate_limiter.py`). When the cap is hit, a request waits and retries automatically instead of failing — no action needed on your end. This limit is not currently configurable via an environment variable.

This only governs how fast *this server* calls KIPRIS; it's separate from your API key's own daily request quota on the KIPRIS developer portal.

Features

Korean Patent Search

Trademark Search

International Patent Search

Search patents from 13 countries via KIPRIS's international database:

Installation

Option 1: Via Smithery (easiest — no local setup required)

Install directly through the Smithery marketplace. Smithery handles the setup and prompts you for your KIPRIS API key:

npx @smithery/cli@latest mcp add greennuri/mcp-kipris

Or visit **smithery.ai/servers/greennuri/mcp-kipris and click Install**.

Option 2: From PyPI

pip install mcp-kipris

Option 3: From Source (development)

git clone https://github.com/nuri428/mcp_kipris.git
cd mcp_kipris

# Option A — using uv (recommended)
pip install uv
uv sync

# Option B — using pip
pip install -e .

Environment Configuration

# Shell export (session-scoped)
export KIPRIS_API_KEY="your_api_key_here"

# Or create a .env file at the project root
echo 'KIPRIS_API_KEY=your_api_key_here' > .env

Running the Server

stdio mode — for Claude Desktop and most MCP clients

# via uv
uv run python -m mcp_kipris.server

# via python directly (if installed with pip install -e .)
python -m mcp_kipris.server

HTTP / SSE mode — for web-based MCP clients

uv run python -m mcp_kipris.sse_server --http --port 6274 --host 0.0.0.0

Via mcpo proxy (stdio → HTTP bridge)

uvx mcpo --port 6274 -- uv run python -m mcp_kipris.server

Docker

bash sse_server_build.sh

Claude Desktop Configuration

Add this block to your Claude Desktop `claude_desktop_config.json`

(usually at `~/Library/Application Support/Claude/` on macOS):

{
  "mcpServers": {
    "kipris": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_kipris.server"],
      "cwd": "/absolute/path/to/mcp_kipris",
      "env": {
        "KIPRIS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Testing

Run the Test Suite

`test/` has two kinds of tests:

• `test/unit/` — fully mocked, no network access, no `KIPRIS_API_KEY` required. Marked `pytest.mark.unit`.
• **Root-level `test_*.py`** — call the live KIPRIS API and require a valid `KIPRIS_API_KEY`. The one pytest-discoverable case is marked `pytest.mark.integration`; the rest are standalone demo scripts guarded by `if __name__ == "__main__":`.

# Install
uv sync --group dev

# Unit tests only — fast, no API key needed
pytest test/unit -v

# Everything except the live-API integration test
pytest test/ -m "not integration" -v

# Full suite with coverage (what CI runs — needs KIPRIS_API_KEY)
pytest test/ -v --cov=src/mcp_kipris --cov-report=term-missing

Individual demo scripts can also be run directly:

python test/test_samsung_patents.py
python test/test_patent_keyword_search.py

Lint and Format

ruff check src/
ruff format src/

Distribution Testing

Before tagging a release, verify the package builds and installs cleanly:

# 1. Build wheel and sdist
pip install build
python -m build

# 2. Smoke-test the wheel in a clean virtualenv
python -m venv /tmp/kipris-smoke
source /tmp/kipris-smoke/bin/activate
pip install dist/mcp_kipris-*.whl
python -c "import mcp_kipris; print('import OK')"
deactivate
rm -rf /tmp/kipris-smoke

# 3. Verify editable install still works
pip install -e .
pytest test/ -v

CI Matrix

Every push and pull request to `main` / `develop` runs the full pipeline on Python 3.11 and 3.12:

API Usage Examples

These examples use the HTTP/SSE server mode. First, get a session ID:

# Start the SSE server
uv run python -m mcp_kipris.sse_server --http --port 6274 --host 0.0.0.0

# Get a session ID
curl -N http://localhost:6274/messages/
# → event: endpoint
# → data: /messages/?session_id=

Search patents by applicant — Samsung Electronics

# "삼성전자" is the Korean name for Samsung Electronics
curl -X POST "http://localhost:6274/messages/?session_id=" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tool",
    "name": "patent_applicant_search",
    "args": {
      "applicant": "삼성전자",
      "docs_count": 5,
      "desc_sort": true
    }
  }'

List all available tools

curl http://localhost:6274/tools | jq .

Response Format

All tools return a Markdown table wrapped in this envelope:

[
  {
    "type": "text",
    "text": "| application_number | title | applicant | ...\n|---|---|---|...",
    "metadata": null
  }
]

Reference

Supported Country Codes (International Search)

Sort Options

Patent Status Codes

ClaudeWork Skill

If you use ClaudeWork, this server is also packaged as a ready-to-use skill:

kipris_skill →

Known Limitations

All 17 tools were exercised against the live KIPRIS API. 16 of them were verified beyond "returns well-formed output" — their output *field values* were cross-checked, not just their shape:

• `ipc_search`, `abstract_search`, `agent_search`, `patent_free_search`, `trademark_search` had a parameter-name mismatch — the tool called its API layer with `docs_count`/`docs_start`, but those methods actually take `num_of_rows`/`page_no`, so the mismatched kwargs went out as query params KIPRIS ignores and the requested count never took effect. Fixed and confirmed live for the first four (requesting N results now returns exactly N); `patent_free_search`'s endpoint turned out to ignore the row-count parameter server-side regardless, so it now trims to N client-side and says so. `trademark_search` got the same fix applied but — see below — couldn't be confirmed live.
• KIPRIS-reported total match counts (`totalCount`) are shown where the endpoint actually provides one (`ipc/abstract/agent_search`, and `trademark_search` once verifiable); the other 9 paginated tools (`patent_applicant_search`, `patent_application_number_search`, `patent_free_search`, `patent_righter_search`, and the 5 foreign tools) call KIPRIS endpoints that never report a total at all, so they now explicitly say so rather than presenting the row count as if it were one.
• Field mappings were spot-checked against a real registered patent (`patent_detail_search`'s 40-field response, cross-referenced against KIPRIS's raw XML) and against each other: `patent_applicant_search`'s publication date/number, and results from `patent_application_number_search`, `patent_righter_search`, and `patent_free_search`, were each re-queried through `patent_detail_search` for the same application and matched exactly; the 5 foreign tools were cross-checked against each other (an applicant-search result looked up again by application number, then by its international application/open number) and returned the same record every time.
• `patent_righter_search`, `patent_advanced_search`/`patent_search`, and 3 of the 5 foreign tools (`foreign_patent_applicant_search`, `foreign_international_application_number_search`, `foreign_international_open_number_search`) used to crash at the MCP protocol level on a validation error (a missing required field, an invalid enum value) instead of returning the normal `"입력값 검증 오류: ..."` text every other tool gives — two had no `try`/`except` around `run_tool()` at all, and the other three re-raised from inside their own `except ValidationError` block, which escapes just as completely as not having one. Confirmed live through the actual `server.call_tool()` path both before and after the fix. All 17 tools are now covered by a regression test that calls each with no arguments and asserts none of them raise.

The one tool still unverified:

• `trademark_search` — every query against this project's KIPRIS API key returns result code 31 (`DEADLINE_EXPIRED`), regardless of the search term. This looks like the key isn't authorized for `trademarkInfoSearchService` specifically (KIPRIS approves some services separately from general patent search), not a bug in this server — but it also means the parameter-name fix above, and the tool's actual output, still haven't been confirmed against a working key.

Tracking issue: #9 — trademark_search verification needed. If you have a KIPRIS API key with trademark search access and can share a raw XML response (success or error), please comment there — we'll use it to verify/fix this tool.

Roadmap

• MCP spec 2026-07-28 upgrade — the MCP specification released 2026-07-28 is a major protocol redesign (stateless sessions, `server/discover`, Streamable HTTP as the only non-deprecated HTTP transport, deprecation of Roots/Sampling/Logging). This server currently pins `mcp[cli]>=1.6.0` (resolved to `1.9.4`), which predates that revision. We'll upgrade once the `mcp` Python SDK ships support for it, and migrate `sse_server.py` off the legacy HTTP+SSE transport (`SseServerTransport`) to Streamable HTTP at the same time.

Contributing

See DEVELOPMENT.md for the full developer guide and CI/CD setup.

1. Fork the repository

2. Create a feature branch: `git checkout -b feature/my-feature`

3. Commit your changes: `git commit -m 'feat: add my feature'`

4. Push: `git push origin feature/my-feature`

5. Open a Pull Request

Before submitting:

ruff check src/   # lint
ruff format src/  # format
pytest test/      # tests (requires KIPRIS_API_KEY)

The `KIPRIS_API_KEY` for CI is stored as a GitHub Secret — you do not need to commit it.

Acknowledgements

Special thanks to **@haseo-ai** for 5 pull requests that significantly expanded this project:

• Abstract search (`AbstractSearchTool`) — search patents by invention abstract
• IPC code search (`IpcSearchTool`) — search by international classification code
• Agent search (`AgentSearchTool`) — search by registered patent agent name
• Trademark search (`TrademarkSearchTool`) — Korean trademark keyword search
• Improved API error handling — more robust error management for KIPRIS API responses

License

MIT License