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=<SESSION_ID>

Search patents by applicant — Samsung Electronics

# "삼성전자" is the Korean name for Samsung Electronics
curl -X POST "http://localhost:6274/messages/?session_id=<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 and verified to return well-formed output, except:

• 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 we haven't been able to confirm the tool's actual output 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