py mcp naver search

This MCP (Multi-platform Communication Protocol) server provides access to Naver Search APIs, allowing AI agents to search for various types of content on Naver.

Overview

• Search for blogs, news, books, images, shopping items, and more
• Multiple search categories with pagination support
• Structured text responses optimized for LLM consumption
• Check for adult content
• Convert keyboard input errors (errata)

Table of Contents

• Prerequisites
• Installation
• Configure MCP Settings
• API Reference
• Acknowledgements
• License

Setup

Prerequisites

• Python 3.12+
• Naver Developer API credentials
• You can obtain these credentials by signing up at the Naver Developers portal.
• And You can check my blog Naver Search API MCP Server, too.

Installation

1. Clone the repository:

   git clone https://github.com/jikime/py-mcp-naver-search.git
   cd py-mcp-naver-search

2. uv installation

   curl -LsSf https://astral.sh/uv/install.sh | sh

3. Create a virtual environment and install dependencies:

   uv venv -p 3.12
   source .venv/bin/activate
   pip install -r requirements.txt

4. Create a .env file with your Naver API credentials:

   cp env.example .env
   vi .env
   
   NAVER_CLIENT_ID=your_client_id_here
   NAVER_CLIENT_SECRET=your_client_secret_here

Using Docker

1. Build the Docker image:

   docker build -t py-mcp-naver-search .

2. Run the container:

   docker run py-mcp-naver-search

Using Local

1. Run the server:

   mcp run server.py

2. Run the MCP Inspector

   mcp dev server.py

Configure MCP Settings

Add the server configuration to your MCP settings file:

Claude desktop app

1. To install automatically via Smithery:

npx -y @smithery/cli install @jikime/py-mcp-naver-search --client claude

1. To install manually open ~/Library/Application Support/Claude/claude_desktop_config.json

Add this to the mcpServers object:

{
  "mcpServers": {
    "Google Toolbox": {
      "command": "/path/to/bin/uv",
      "args": [
        "--directory",
        "/path/to/py-mcp-naver-search",
        "run",
        "server.py"
      ]
    }
  }
}

Cursor IDE

open ~/.cursor/mcp.json

Add this to the mcpServers object:

{
  "mcpServers": {
    "Google Toolbox": {
      "command": "/path/to/bin/uv",
      "args": [
        "--directory",
        "/path/to/py-mcp-naver-search",
        "run",
        "server.py"
      ]
    }
  }
}

for Docker

{
  "mcpServers": {
    "Google Toolbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "py-mcp-naver-search"
      ]
    }
  }
}

Using the Client

The repository includes a client script for testing:

# Basic search
uv run client.py blog "Python programming" display=5 page=1

# News search with sorting
uv run client.py news "AI" display=10 page=1 sort=date

# Image search with filtering
uv run client.py image "cat" display=10 filter=large

# Check for adult content
uv run client.py adult "your query"

# Errata correction
uv run client.py errata "spdlqj"

Available Search Categories

The server supports the following search categories:

1. blog - Blog posts
2. news - News articles
3. book - Books
4. adult - Adult content check
5. encyc - Encyclopedia entries
6. cafe_article - Cafe articles
7. kin - Knowledge iN Q&A
8. local - Local business information
9. errata - Keyboard input error correction
10. shop - Shopping items
11. doc - Academic papers and documents
12. image - Images
13. webkr - Web documents

API Reference

Tools

Search Blog

search_blog(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str

Search News

search_news(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str

Search Book

search_book(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str

Check Adult Query

check_adult_query(query: str) -> str

Search Encyclopedia

search_encyclopedia(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str

Search Cafe Article

search_cafe_article(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str

Search KnowledgeiN

search_kin(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str

Search Local

search_local(query: str, display: int = 5, page: int = 1, sort: str = "random") -> str

Correct Errata

correct_errata(query: str) -> str

Search Shop

search_shop(query: str, display: int = 10, page: int = 1, sort: str = "sim") -> str

Search Document

search_doc(query: str, display: int = 10, page: int = 1) -> str

Search Image

search_image(query: str, display: int = 10, page: int = 1, sort: str = "sim", filter: str = "all") -> str

Search Web Document

search_webkr(query: str, display: int = 10, page: int = 1) -> str

Resources

Available Search Categories

GET naver://available-search-categories

Response Format

All tools return responses in structured text format, optimized for LLM processing:

Naver Blog search results (total 12,345 of 1~10):

### Result 1
Title(title): Sample Blog Post
Link(link): https://blog.example.com/post1
Description(description): This is a sample blog post about...
Blogger name(bloggername): John Doe
Blogger link(bloggerlink): https://blog.example.com
Post date(postdate): 20250429

### Result 2
...

Acknowledgements

• Naver Search API MCP Server Blog
• Naver Open API
• MCP Protocol

License

This project is licensed under the MIT License - see the LICENSE file for details.