py-mcp-server-template

이 저장소는 Python으로 MCP(Model Context Protocol) 서버를 직접 만드는 데 도움이 되는 템플릿입니다. 시작하려면 이 저장소를 포크하세요.

uv로 설정

이 프로젝트는 Python 패키징 및 가상 환경 관리를 위해 uv 사용합니다. uv 설치되어 있지 않으면 공식 uv 설치 가이드 를 참조하세요.

1. 포크된 저장소를 복제하세요.

   지엑스피1

2. 가상 환경을 만들고 활성화합니다. uv 일반적으로 프로젝트 루트에 .venv 디렉토리를 만듭니다.

   uv venv
   source .venv/bin/activate  # On macOS/Linux
   # .venv\Scripts\activate   # On Windows

3. 종속성 설치: 이 프로젝트에서는 pyproject.toml 사용하여 종속성을 관리합니다.

   uv pip install .

   새로운 종속성을 추가하는 경우 pyproject.toml 파일에 정의하고 이 명령을 다시 실행하세요. requirements.txt 파일을 사용하는 경우 uv pip install -r requirements.txt 사용하여 설치할 수 있습니다.

Related MCP server: mcp-framework-starter

서버 실행

mcp_server.py 스크립트는 MCP 서버를 시작합니다.

서버를 직접 실행하려면:

uv run python mcp_server.py

Claude Desktop 또는 Cursor와 통합

Claude Desktop이나 Cursor와 같은 애플리케이션에서 이 MCP 서버를 사용하려면 애플리케이션 설정에서 서버를 구성해야 합니다. 일반적으로 구성에는 서버를 실행할 명령을 지정하는 작업이 포함됩니다.

다음은 구성 스니펫 예시입니다. /ABSOLUTE/PATH/TO/PARENT/FOLDER/YOUR_REPOSITORY_NAME 시스템의 프로젝트 디렉터리에 대한 실제 절대 경로로 바꿔야 합니다.

{
    "mcpServers": {
        "my-custom-python-server": {
            "command": "uv",
            "args": [
                "run",
                "--python",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/YOUR_REPOSITORY_NAME/.venv/bin/python",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/YOUR_REPOSITORY_NAME/mcp_server.py"
            ],
            "workingDirectory": "/ABSOLUTE/PATH/TO/PARENT/FOLDER/YOUR_REPOSITORY_NAME"
        }
    }
}

구성에 대한 설명:

• "my-custom-python-server" : 서버 구성에 지정하는 이름입니다.

• "command": "uv" : 실행할 명령으로 uv 지정합니다.

• "args" : uv 명령에 대한 인수 목록입니다.

  • "run" : uv 관리되는 환경 내에서 명령을 실행하라고 알립니다.

  • "--python" : 사용할 Python 인터프리터를 지정합니다. uv 가상 환경( .venv/bin/python ) 내의 Python 인터프리터를 지정하는 것이 중요합니다.

  • "/ABSOLUTE/PATH/TO/PARENT/FOLDER/YOUR_REPOSITORY_NAME/mcp_server.py" : 서버 스크립트의 절대 경로입니다.

• "workingDirectory" : 서버 프로세스의 작업 디렉토리를 지정합니다. 이는 프로젝트의 루트 디렉토리여야 합니다.

중요한:

• args 와 workingDirectory 의 경로가 시스템에 맞는지 확인하세요.

• 애플리케이션에서 uv 찾을 수 없는 경우 "command" 필드에 전체 경로를 지정해야 할 수 있습니다. 일반적으로 macOS 또는 Linux에서는 터미널에서 which uv 실행하고, Windows에서는 where uv 실행하여 경로를 찾을 수 있습니다.

• 서버는 기본적으로 mcp_server.py ( mcp.run(transport='stdio') )에 구성된 대로 stdio 를 수신합니다. 이는 일반적으로 Cursor와 같은 애플리케이션이 기대하는 바와 같습니다.

구성 후, 애플리케이션은 Python MCP 서버와 통신할 수 있어야 합니다.