pocketbase-mcp

PocketBase를 위한 Model Context Protocol (MCP) 서버입니다. 깔끔한 Pythonic 인터페이스를 통해 Claude와 같은 AI 어시스턴트가 귀하의 PocketBase 백엔드에 완전히 액세스할 수 있도록 합니다.

개요

pocketbase-mcp는 LLM과 PocketBase 인스턴스 사이의 가교 역할을 합니다. 연결되면 AI 어시스턴트는 자연어를 통해 컬렉션 목록 조회, 레코드 CRUD 작업, 인증 관리, 파일 업로드 처리 및 데이터베이스 관리를 수행할 수 있습니다.

FastMCP(표준 Python MCP 프레임워크)로 구축되었으며, PocketBase REST API와의 비동기 HTTP 통신을 위해 httpx를 사용합니다.

Related MCP server: PocketBase MCP Server

주요 기능

• 레코드 — 모든 컬렉션의 레코드 목록 조회, 가져오기, 생성, 업데이트, 삭제 및 일괄 작업

• 컬렉션 — 컬렉션 스키마 목록 조회, 검사, 생성, 업데이트 및 삭제

• 인증 — 이메일/비밀번호 또는 API 키를 통해 슈퍼유저 또는 일반 사용자로 인증

• 파일 — 파일 토큰 생성 및 선택적 이미지 변환을 포함한 파일 URL 검색

• 설정 — 애플리케이션 설정 읽기 및 업데이트

• 필터링 및 페이지네이션 — PocketBase 필터 표현식, 정렬, 확장 및 페이지네이션 매개변수를 직접 전달

• 실시간 인식 — 향후 확장을 위해 SSE 구독 패턴을 고려하여 설계됨

요구 사항

• Python 3.11+

• 실행 중인 PocketBase 인스턴스 (로컬 또는 원격)

• uv (권장) 또는 pip

설치

pip 사용

pip install pocketbase-mcp

구성

서버는 환경 변수를 통해 구성됩니다:

.env 파일에 설정하거나 직접 내보내십시오:

export POCKETBASE_URL=http://127.0.0.1:8090
export POCKETBASE_SUPERUSER_EMAIL=admin@example.com
export POCKETBASE_SUPERUSER_PASSWORD=your-password

서버 실행

stdio 전송 (기본값 — Claude Desktop, Claude Code 등용)

pocketmcp

MCP Inspector 사용 (개발 및 테스트용)

# Terminal 1
pocketmcp

# Terminal 2
npx @modelcontextprotocol/inspector
# Connect to: http://localhost:8000/mcp

Claude에 연결

Claude Desktop

claude_desktop_config.json에 다음을 추가하십시오:

{
  "mcpServers": {
    "pocketbase": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/pocketbase-mcp/server.py"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_SUPERUSER_EMAIL": "admin@example.com",
        "POCKETBASE_SUPERUSER_PASSWORD": "your-password"
      }
    }
  }
}

사용 가능한 도구

레코드

컬렉션

인증

파일

설정

프로젝트 구조

pocketbase-mcp/
├── server.py            # MCP server entry point (FastMCP)
├── tools/
│   ├── records.py       # Record CRUD tools
│   ├── collections.py   # Collection management tools
│   ├── auth.py          # Authentication tools
│   ├── files.py         # File tools
│   └── settings.py      # Settings tools
├── client.py            # Async PocketBase HTTP client (httpx)
├── config.py            # Environment variable loading
├── pyproject.toml
└── README.md

사용 예시

Claude에 연결되면 자연어를 통해 PocketBase 인스턴스와 상호 작용할 수 있습니다:

"posts 컬렉션에서 status = 'published'인 모든 레코드를 created 내림차순으로 정렬하여 나열해 줘."

"users 컬렉션에 이름이 'Alice'이고 역할이 'editor'인 새 레코드를 생성해 줘."

"products 컬렉션의 스키마를 보여줘."

"comments에서 ID가 ae40239d2bc4477인 레코드를 삭제해 줘."

"PocketBase 설정에서 앱 이름을 'My App'으로 업데이트해 줘."

PocketBase 호환성

이 MCP 서버는 **PocketBase v0.36.9+**를 대상으로 합니다. 배치 API를 사용하려면 PocketBase 대시보드의 Settings → Application에서 명시적으로 활성화해야 합니다.

보안 참고 사항

• 자격 증명을 버전 제어에 커밋하지 마십시오. 환경 변수나 .env 파일을 사용하십시오 (.gitignore에 .env 추가).

• 프로덕션 배포 시에는 이메일/비밀번호보다 API 키 인증을 사용하는 것이 좋습니다.

• PocketBase의 컬렉션 API 규칙은 인증된 사용자가 실제로 액세스할 수 있는 항목을 제어하며, pocketbase-mcp는 이러한 규칙을 준수합니다.

기여

기여를 환영합니다! 중요한 변경 사항에 대한 풀 리퀘스트를 제출하기 전에 이슈를 열어주십시오.

1. 저장소 포크

2. 기능 브랜치 생성 (git checkout -b feat/my-feature)

3. 변경 사항 커밋

4. 풀 리퀘스트 열기

라이선스

MIT 라이선스. 자세한 내용은 LICENSE를 참조하십시오.