{"id":32518138,"url":"https://github.com/meloncafe/chromadb-remote-mcp","last_synced_at":"2026-05-14T09:06:01.289Z","repository":{"id":320706518,"uuid":"1082926954","full_name":"meloncafe/chromadb-remote-mcp","owner":"meloncafe","description":"Remote MCP server for ChromaDB","archived":false,"fork":false,"pushed_at":"2026-05-05T22:43:00.000Z","size":1076,"stargazers_count":12,"open_issues_count":2,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T00:35:44.181Z","etag":null,"topics":["chromadb","claude","claude-code","claude-desktop","claude-mobile","docker","mcp","model-context-protocol","remote-mcp","remote-mcp-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meloncafe.png","metadata":{"files":{"readme":"README.ko.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.ko.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.ko.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.ko.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["meloncafe"],"patreon":"meloncafe"}},"created_at":"2025-10-25T02:20:49.000Z","updated_at":"2026-05-05T22:43:02.000Z","dependencies_parsed_at":"2025-11-28T12:04:59.048Z","dependency_job_id":null,"html_url":"https://github.com/meloncafe/chromadb-remote-mcp","commit_stats":null,"previous_names":["meloncafe/chromadb-remote-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/meloncafe/chromadb-remote-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meloncafe%2Fchromadb-remote-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meloncafe%2Fchromadb-remote-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meloncafe%2Fchromadb-remote-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meloncafe%2Fchromadb-remote-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meloncafe","download_url":"https://codeload.github.com/meloncafe/chromadb-remote-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meloncafe%2Fchromadb-remote-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32771079,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T02:36:36.067Z","status":"ssl_error","status_checked_at":"2026-05-08T02:36:07.210Z","response_time":54,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chromadb","claude","claude-code","claude-desktop","claude-mobile","docker","mcp","model-context-protocol","remote-mcp","remote-mcp-server"],"created_at":"2025-10-28T03:01:11.311Z","updated_at":"2026-05-08T07:34:04.961Z","avatar_url":"https://github.com/meloncafe.png","language":"TypeScript","funding_links":["https://github.com/sponsors/meloncafe","https://patreon.com/meloncafe"],"categories":[],"sub_categories":[],"readme":"# ChromaDB Remote MCP Server\n\n[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-blue)](https://modelcontextprotocol.io)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![MseeP.ai](https://img.shields.io/badge/MseeP.ai-Audited-4c1)](https://mseep.ai/app/meloncafe-chromadb-remote-mcp)\n[![codecov](https://codecov.io/gh/meloncafe/chromadb-remote-mcp/graph/badge.svg?token=0abUQsve4y)](https://codecov.io/gh/meloncafe/chromadb-remote-mcp)\n[![DeepSource](https://app.deepsource.com/gh/meloncafe/chromadb-remote-mcp.svg/?label=Active+Issues\u0026show_trend=true\u0026token=Mzfb6tMnlzBIxaJO9CsYO3e8)](https://app.deepsource.com/gh/meloncafe/chromadb-remote-mcp/)\n\n**Streamable HTTP** 방식의 MCP(Model Context Protocol) 서버로, Claude와 같은 AI 어시스턴트가 원격에서 ChromaDB에 접근할 수 있도록 합니다. 모바일 기기와 원격 위치에서 의미 검색 및 벡터 데이터베이스 작업을 지원합니다.\n\n\u003e **중요**: 이 프로젝트는 MCP Streamable HTTP (2025-03-26 스펙)를 사용합니다. SSE 전송 방식은 더 이상 사용되지 않습니다.\n\n[English Documentation](README.md)\n\n---\n\n## 다중 플랫폼 AI 메모리 서버\n\n**다양한 AI 플랫폼 서비스를 지원합니다.:**\n\n- Claude (Desktop, Mobile, Code)\n- Gemini (CLI, Code Assist)\n- Cursor, Cline, Windsurf, VS Code Copilot\n- 그리고 Remote MCP를 사용할 수 있는 모든 도구\n\n## 주요 기능\n\n모든 Claude 클라이언트(Desktop, Code, Mobile)가 동일한 자가 호스팅 ChromaDB 인스턴스에 접근할 수 있는 원격 MCP 서버입니다.\n\n- **기기 간 공유 메모리** - 모든 Claude 클라이언트가 동일한 ChromaDB 인스턴스 사용\n- **자가 호스팅 및 프라이빗** - 데이터가 본인의 인프라에 보관됨\n- **원격 접근** - Tailscale 또는 공개 인터넷을 통해 어디서나 접근\n- **완전한 ChromaDB 지원** - MCP 도구를 통한 모든 CRUD 작업\n- **REST API 프록시** - Python/JavaScript의 직접 ChromaDB 접근\n- **통합 인증** - 단일 토큰으로 MCP와 REST API 모두 보호\n- **간편한 배포** - 원 커맨드 설치\n\n---\n\n## 아키텍처\n\n### 개요\n\n```\n┌──────────────────────────────┐     ┌──────────────┐\n│   Claude Desktop + Mobile    │     │  Claude Code │\n│   (커스텀 커넥터 - 자동 동기화)    │     │   (CLI 설정)  │\n└──────────────┬───────────────┘     └──────┬───────┘\n               │                            │\n               │        MCP 원격 커넥터        │\n               └─────────────┬──────────────┘\n                             │ HTTPS\n                   ┌─────────▼──────────┐\n                   │   원격 MCP          │\n                   │   서버 (Node.js)    │\n                   │                    │\n                   │ • 인증 게이트웨이      │\n                   │ • MCP 프로토콜       │\n                   │ • REST API 프록시   │\n                   └─────────┬──────────┘\n                             │\n                   ┌─────────▼──────────┐\n                   │   ChromaDB         │\n                   │   (벡터 데이터베이스)  │\n                   │                    │\n                   │ • 임베딩            │\n                   │ • 컬렉션            │\n                   │ • 의미 검색          │\n                   └────────────────────┘\n\n```\n\n**클라이언트 연결 방법:**\n\n- **Claude Desktop + Mobile**: Claude Desktop에서 커스텀 커넥터로 한 번 설정하면 모바일 앱에 자동으로 동기화됩니다. 두 앱이 동일한 연결을 자동으로 공유합니다.\n- **Claude Code**: `claude mcp add` CLI 명령어를 사용하여 별도로 설정해야 합니다.\n\n모든 클라이언트가 이 원격 MCP 서버를 통해 동일한 자가 호스팅 ChromaDB에 접근합니다. 벡터 임베딩과 의미 검색 결과가 모든 플랫폼에서 지속됩니다.\n\n### API 엔드포인트\n\n| 경로            | 목적              | 클라이언트                 | 인증 |\n| --------------- | ----------------- | -------------------------- | ---- |\n| `/mcp`          | MCP 프로토콜      | Claude Desktop/Code/Mobile | ✅   |\n| `/api/v2/*`     | ChromaDB REST API | Python                     | ✅   |\n| `/docs`         | Swagger UI        | 브라우저 (API 문서)        | ✅   |\n| `/openapi.json` | OpenAPI 스펙      | API 도구                   | ✅   |\n| `/health`       | 헬스 체크         | 모니터링                   | ❌   |\n\n### 작동 방식\n\n1. **Claude Desktop/Mobile**: 커스텀 커넥터로 MCP 서버 추가 (기기 간 자동 동기화)\n2. **Claude Code**: `claude mcp add` CLI 명령어로 MCP 서버 추가\n3. **원격 MCP 서버**가 요청을 인증하고 MCP 프로토콜을 ChromaDB 작업으로 변환\n4. **ChromaDB**가 의미 검색을 위한 벡터 임베딩을 저장하고 검색\n5. **Python**도 프록시된 REST API를 통해 ChromaDB에 직접 접근 가능\n\n**장점:**\n\n- 모든 클라이언트에서 동일한 벡터 데이터베이스\n- Desktop과 Mobile 간 연결 자동 공유\n- 자가 호스팅 및 프라이빗\n- 앱 재시작 후에도 지속되는 메모리\n- 임베딩의 단일 소스\n\n---\n\n## 빠른 시작\n\n### 원 커맨드 설치\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/scripts/install.sh | bash\n```\n\n다음 작업을 자동으로 수행합니다:\n\n1. `docker-compose.yml`과 `.env.example` 다운로드\n2. Docker Compose 명령어 자동 감지 (`docker-compose` 또는 `docker compose`)\n3. 보안 인증 토큰 자동 생성 (선택 사항)\n4. ChromaDB 데이터 저장 위치 설정 (Docker 볼륨, 로컬 디렉토리, 또는 커스텀 경로)\n5. Docker 이미지 풀\n6. 생성된 인증 토큰 및 연결 URL 표시\n\n### 수동 설치\n\n#### 옵션 1: Docker (권장 - 사전 빌드된 이미지)\n\n```bash\n# 설정 파일 다운로드\nmkdir chromadb-remote-mcp \u0026\u0026 cd chromadb-remote-mcp\ncurl -O https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/docker-compose.yml\ncurl -O https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/.env.example\n\n# 환경 설정\ncp .env.example .env\n# .env를 수정하여 다음 항목 설정:\n#   - MCP_AUTH_TOKEN (토큰 생성 방법은 아래 참조)\n#   - PORT (기본값: 8080)\n#   - CHROMA_DATA_PATH (기본값: chroma-data)\n\n# 서비스 시작\ndocker compose up -d\n# 또는: docker-compose up -d (구버전의 경우)\n\n# 헬스 체크\ncurl http://localhost:8080/health\n\n# 로그 확인\ndocker compose logs -f\n```\n\n#### 옵션 2: 소스에서 빌드\n\n```bash\n# 저장소 클론\ngit clone https://github.com/meloncafe/chromadb-remote-mcp.git\ncd chromadb-remote-mcp\n\n# 환경 설정\ncp .env.example .env\n# .env 수정\n\n# docker-compose로 시작 (소스에서 이미지 빌드)\ndocker compose -f docker-compose.dev.yml up -d\n# 또는: docker-compose -f docker-compose.dev.yml up -d (구버전의 경우)\n```\n\n#### 옵션 3: 로컬 개발\n\n```bash\n# 클론 및 설치\ngit clone https://github.com/meloncafe/chromadb-remote-mcp.git\ncd chromadb-remote-mcp\nyarn install\n\n# 환경 설정\ncp .env.example .env\n# .env 파일 수정\n\n# 빌드 및 실행\nyarn build\nyarn start\n```\n\n### 보안 토큰 생성\n\n프로덕션 환경에서는 `.env`의 `MCP_AUTH_TOKEN`에 안전한 토큰을 생성하세요:\n\n```bash\n# 방법 1: Node.js (권장)\nnode -e \"console.log(require('crypto').randomBytes(32).toString('base64url'))\"\n\n# 방법 2: OpenSSL\nopenssl rand -base64 32 | tr '+/' '-_' | tr -d '='\n```\n\n생성된 토큰을 `.env` 파일에 붙여넣으세요:\n\n```env\nMCP_AUTH_TOKEN=생성된-토큰-여기에\n```\n\n### 서버 엔드포인트\n\n- MCP: `http://localhost:8080/mcp` (Caddy 프록시를 통해)\n- Health: `http://localhost:8080/health`\n- ChromaDB API: `http://localhost:8080/api/v2/*`\n- Swagger UI: `http://localhost:8080/docs`\n\n---\n\n## 설정\n\n### 환경 변수 (.env 파일)\n\n모든 설정은 `.env` 파일을 통해 이루어집니다. `.env.example`을 `.env`로 복사하여 사용자 정의하세요:\n\n```bash\ncp .env.example .env\n```\n\n| 변수                | 설명                                                            | 기본값             | 필수                  |\n| ------------------- | --------------------------------------------------------------- | ------------------ | --------------------- |\n| `PORT`              | 외부 포트 (Caddy 리버스 프록시)                                 | `8080`             | 아니오                |\n| `CHROMA_DATA_PATH`  | ChromaDB 데이터 저장 경로 (볼륨 이름, `./data`, 또는 절대 경로) | `chroma-data`      | 아니오                |\n| `CHROMA_HOST`       | ChromaDB 호스트 (내부)                                          | `chromadb`         | 아니오                |\n| `CHROMA_PORT`       | ChromaDB 포트 (내부)                                            | `8000`             | 아니오                |\n| `CHROMA_TENANT`     | ChromaDB 테넌트                                                 | `default_tenant`   | 아니오                |\n| `CHROMA_DATABASE`   | ChromaDB 데이터베이스                                           | `default_database` | 아니오                |\n| `MCP_AUTH_TOKEN`    | MCP 및 REST API 인증 토큰                                       | -                  | **예** (공개 접근 시) |\n| `CHROMA_AUTH_TOKEN` | ChromaDB 인증 토큰 (ChromaDB에서 인증이 필요한 경우)            | -                  | 아니오                |\n| `RATE_LIMIT_MAX`    | IP당 15분당 최대 요청 수                                        | `100`              | 아니오                |\n| `ALLOWED_ORIGINS`   | 허용된 origin 목록 (쉼표로 구분, DNS rebinding 방어)            | -                  | 아니오                |\n| `ALLOW_QUERY_AUTH`  | 쿼리 파라미터 인증 활성화 (`?apiKey=TOKEN`)                     | `true`             | 아니오                |\n\n### 인증\n\n**중요:** 공개 인터넷 접근(Tailscale Funnel, Cloudflare Tunnel 등)을 위해서는 `.env` 파일에 `MCP_AUTH_TOKEN`을 **반드시** 설정해야 합니다.\n\n보안 토큰 생성:\n\n```bash\n# 방법 1: Node.js (권장 - .env.example 참조)\nnode -e \"console.log(require('crypto').randomBytes(32).toString('base64url'))\"\n\n# 방법 2: OpenSSL\nopenssl rand -base64 32 | tr '+/' '-_' | tr -d '='\n```\n\n`.env` 파일 수정:\n\n```env\nMCP_AUTH_TOKEN=생성된-토큰-여기에\n```\n\n서비스 재시작:\n\n```bash\ndocker compose restart\n# 또는: docker-compose restart\n```\n\n**지원되는 인증 방식:**\n\n1. **Authorization 헤더** (가장 안전함): `Authorization: Bearer TOKEN`\n\n   - API 클라이언트 및 자동화 도구에 권장\n   - MCP 사양 준수\n   - 예시: `curl -H \"Authorization: Bearer YOUR_TOKEN\"`\n\n2. **X-Chroma-Token 헤더**: `X-Chroma-Token: TOKEN`\n\n   - ChromaDB Python/JavaScript 라이브러리용\n   - ChromaDB 클라이언트 SDK와 호환\n   - 예시: `client = chromadb.HttpClient(headers={\"X-Chroma-Token\": \"TOKEN\"})`\n\n3. **Query Parameter** (기본 활성화): `?apiKey=TOKEN`\n   - **Claude Desktop Custom Connector에 필수**\n   - 브라우저 기반 통합 지원\n   - 기본적으로 활성화됨 (`ALLOW_QUERY_AUTH=true`)\n   - 필요하지 않은 경우 `ALLOW_QUERY_AUTH=false`로 비활성화 가능\n\n### Origin 헤더 검증 (DNS Rebinding 방어)\n\n서버는 브라우저 요청에 대해 `Origin` 헤더를 검증하여 DNS rebinding 공격을 방지합니다. 이 보안 기능은 기본적으로 활성화되어 있으며 로컬 MCP 서버를 악의적인 웹사이트로부터 보호합니다.\n\n**기본 허용 origin (항상 허용됨):**\n\n- **Localhost 변형**: `localhost`, `127.0.0.1`, `[::1]`\n- **Claude.ai 도메인**: `https://claude.ai`, `https://api.anthropic.com`\n\n**추가 허용 origin 설정:**\n\n추가 웹 애플리케이션이나 커스텀 도메인을 허용해야 하는 경우, `.env` 파일의 `ALLOWED_ORIGINS`에 추가하세요:\n\n```env\n# 추가 커스텀 도메인 설정 (Claude.ai는 기본으로 허용됨)\nALLOWED_ORIGINS=https://myapp.com,https://yourdomain.com\n```\n\n**ALLOWED_ORIGINS 설정이 필요한 경우:**\n\n- ✅ Claude Desktop Custom Connector 사용 → **설정 불필요** (기본 허용)\n- ✅ 커스텀 웹 애플리케이션에서 접근 → 애플리케이션 도메인 추가\n- ✅ Swagger UI 원격 접근 → 서버 도메인 추가\n- ❌ Claude Code CLI 사용 → 불필요 (Origin 헤더 없음)\n- ❌ Python/JavaScript 클라이언트 사용 → 불필요 (Origin 헤더 없음)\n- ❌ 로컬 개발만 사용 → 불필요 (localhost는 기본 허용)\n\n**설정 예시:**\n\n```env\n# 커스텀 웹 애플리케이션용\nALLOWED_ORIGINS=https://myapp.com,https://app.mycompany.com\n\n# 여러 커스텀 도메인 (쉼표로 구분, 공백은 자동 제거)\nALLOWED_ORIGINS=https://myapp.com, https://api.example.com, https://dashboard.mycompany.com\n\n# Claude.ai와 localhost만 필요한 경우 비워두기\nALLOWED_ORIGINS=\n```\n\n**참고:** Claude.ai 도메인(`https://claude.ai`, `https://api.anthropic.com`)과 localhost는 `ALLOWED_ORIGINS`가 비어있어도 항상 허용됩니다. Origin 헤더가 없는 서버 간 요청은 항상 허용됩니다.\n\n### 데이터 저장 설정\n\nChromaDB 데이터는 세 가지 방식으로 저장할 수 있습니다:\n\n1. **Docker 볼륨 (기본값)**: `CHROMA_DATA_PATH=chroma-data`\n\n   - Docker가 관리\n   - 컨테이너 재시작 후에도 유지됨\n   - `docker volume ls` 및 `docker volume inspect chroma-data` 명령어로 위치 확인\n\n2. **로컬 디렉토리**: `CHROMA_DATA_PATH=./data`\n\n   - 백업 및 접근이 용이함\n   - 설치 디렉토리에 저장됨\n\n3. **커스텀 경로**: `CHROMA_DATA_PATH=/path/to/data`\n   - 절대 경로여야 함\n   - 외부 스토리지 마운트에 유용함\n\n`CHROMA_DATA_PATH` 변경 후 서비스를 재시작하세요:\n\n```bash\ndocker compose restart\n```\n\n---\n\n## Claude 연결\n\n### Claude Desktop + Mobile\n\n**방법 1: Custom Connector (권장 - Pro/Team/Enterprise)**\n\n1. Claude Desktop → Settings → Integrations → Custom Connector 열기\n2. \"Add Custom Server\" 클릭\n3. 입력:\n   - **Name**: `ChromaDB`\n   - **URL**: `https://your-server.com/mcp?apiKey=YOUR_TOKEN`\n\n\u003e **참고**: Custom connector는 모바일 앱에 자동으로 동기화됩니다. 원격 접근 시 인증이 필수입니다.\n\n**방법 2: mcp-remote 래퍼 (Free/Pro 사용자)**\n\nCustom Connector 접근 권한이 없는 경우 `mcp-remote` 패키지를 사용하세요:\n\n**설정 파일 위치:**\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n**설정 파일에 추가:**\n\n```json\n{\n  \"mcpServers\": {\n    \"chromadb\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote\", \"https://your-server.com/mcp?apiKey=YOUR_TOKEN\"]\n    }\n  }\n}\n```\n\n파일 수정 후 Claude Desktop을 재시작하세요.\n\n\u003e **중요**: 원격 MCP 서버는 `claude_desktop_config.json`에서 `streamableHttp` transport를 사용하여 직접 설정할 수 없습니다. Custom Connector 또는 `mcp-remote` 래퍼 패키지를 사용해야 합니다.\n\n### Claude Code\n\n**CLI 명령어:**\n\n```bash\n# 인증 없이\nclaude mcp add --transport http chromadb https://your-server.com/mcp\n\n# 인증 포함 (Query Parameter - 권장)\nclaude mcp add --transport http chromadb https://your-server.com/mcp?apiKey=YOUR_TOKEN\n\n# 인증 포함 (Header)\nclaude mcp add --transport http chromadb https://your-server.com/mcp \\\n  --header \"Authorization: Bearer YOUR_TOKEN\"\n\n# 확인\nclaude mcp list\n```\n\n---\n\n## 사용 가능한 도구\n\nMCP 서버는 Claude용으로 다음 도구를 제공합니다:\n\n### 컬렉션 관리\n\n- `chroma_list_collections` - 모든 컬렉션 목록 조회\n- `chroma_create_collection` - 새 컬렉션 생성\n- `chroma_delete_collection` - 컬렉션 삭제\n- `chroma_get_collection_info` - 컬렉션 메타데이터 조회\n- `chroma_get_collection_count` - 문서 개수 조회\n- `chroma_peek_collection` - 컬렉션 내용 미리보기\n\n### 문서 작업\n\n- `chroma_add_documents` - 임베딩과 함께 문서 추가\n- `chroma_query_documents` - 의미 검색 (벡터 유사도)\n- `chroma_get_documents` - ID 또는 필터로 문서 조회\n- `chroma_update_documents` - 기존 문서 수정\n- `chroma_delete_documents` - 문서 삭제\n\n---\n\n## Python에서 ChromaDB 사용하기\n\nMCP 서버는 모든 ChromaDB REST API 엔드포인트를 프록시하여 Python 클라이언트의 직접 접근을 허용합니다.\n\n### Python 예제\n\n```python\nimport chromadb\n\n# HTTPS (Tailscale Funnel, 공개 배포)\nclient = chromadb.HttpClient(\n    host=\"your-server.com\",\n    port=443,\n    ssl=True,\n    headers={\n        \"X-Chroma-Token\": \"YOUR_TOKEN\"\n    }\n)\n\n# 로컬 개발 (HTTP)\nclient = chromadb.HttpClient(\n    host=\"localhost\",\n    port=8080,\n    ssl=False,\n    headers={\n        \"X-Chroma-Token\": \"YOUR_TOKEN\"\n    }\n)\n\n# 사용\ncollection = client.create_collection(\"my_collection\")\ncollection.add(\n    documents=[\"문서 1\", \"문서 2\"],\n    ids=[\"id1\", \"id2\"]\n)\nresults = collection.query(query_texts=[\"검색어\"], n_results=2)\n```\n\n대체 인증 방법:\n\n```python\nfrom chromadb.config import Settings\n\nclient = chromadb.HttpClient(\n    host=\"your-server.com\",\n    port=443,\n    ssl=True,\n    settings=Settings(\n        chroma_client_auth_provider=\"chromadb.auth.token_authn.TokenAuthClientProvider\",\n        chroma_client_auth_credentials=\"YOUR_TOKEN\"\n    )\n)\n```\n\n### API 문서\n\nChromaDB REST API 엔드포인트의 Swagger UI 문서: `https://your-server.com/docs`\n\n---\n\n## 배포\n\n### 옵션 1: Tailscale VPN (권장)\n\n**Tailscale 네트워크 내에서 안전한 접근:**\n\n```bash\n# 서비스 시작\ndocker compose up -d\n\n# Tailscale Serve 활성화 (자동 인증서가 포함된 HTTPS)\ntailscale serve https / http://127.0.0.1:8080\n\n# 상태 확인\ntailscale serve status\n```\n\n이제 서버는 Tailnet의 모든 기기에서 `https://your-machine.tailXXXXX.ts.net`으로 접근할 수 있습니다.\n\n**장점:**\n\n- 자동 HTTPS 인증서\n- 공개 인터넷 노출 없음\n- 암호화된 VPN 터널\n- 인증 선택 사항 (VPN이 보안 계층 제공)\n\n### 옵션 2: Tailscale Funnel (공개 인터넷)\n\n**Claude Desktop UI Custom Connector를 사용하거나 공개적으로 공유하려면:**\n\n```bash\n# Funnel 활성화 (공개 인터넷 접근 허용)\ntailscale funnel 8080 on\ntailscale serve https / http://127.0.0.1:8080\n\n# Funnel이 활성화되었는지 확인\ntailscale serve status  # \"Funnel on\" 표시되어야 함\n```\n\n\u003e **경고**: 이는 서버를 공개 인터넷에 노출합니다. **인증이 필수입니다!** 환경에 `MCP_AUTH_TOKEN`을 설정하세요.\n\n**Funnel 비활성화:**\n\n```bash\ntailscale funnel 8080 off\n```\n\n### 옵션 3: Cloudflare Tunnel\n\n```bash\n# cloudflared 설치\ncurl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared\nchmod +x cloudflared\n\n# 인증\n./cloudflared tunnel login\n\n# 터널 생성\n./cloudflared tunnel create chroma-mcp\n\n# 터널 실행\n./cloudflared tunnel --url http://localhost:3000\n```\n\n### 옵션 4: Nginx 리버스 프록시\n\n```nginx\nserver {\n    listen 80;\n    server_name your-domain.com;\n\n    location / {\n        proxy_pass http://localhost:3000;\n        proxy_http_version 1.1;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n    }\n}\n```\n\n---\n\n## 보안\n\n### 코드 품질 및 보안 분석\n\n이 프로젝트는 엄격한 보안 관행을 따르며 정적 분석으로 식별된 모든 보안 문제를 해결했습니다:\n\n- ✅ **활성 이슈 0개**: 모든 OWASP 및 CWE 보안 문제 해결 완료\n- 🔒 **정적 분석**: [DeepSource](https://app.deepsource.com/report/1328a083-a457-4598-b56f-e64dafdbcc28)를 통한 지속적인 모니터링\n- 🛡️ **보안 표준**: OWASP Top 10 및 Node.js 보안 모범 사례 준수\n- 📊 **자동 스캔**: Dependabot, CodeQL, 컨테이너 취약점 스캐닝\n\n자세한 보안 정보는 [보안 정책](SECURITY.md)을 참조하세요.\n\n### 보안 권장사항\n\n1. **공개 접근을 위한 인증 활성화**\n\n   - Tailscale Funnel이나 공개 인터넷 사용 시 `MCP_AUTH_TOKEN` 설정\n   - 강력한 토큰 생성: `openssl rand -base64 32 | tr '+/' '-_' | tr -d '='`\n   - 정기적으로 토큰 교체\n\n2. **HTTPS 사용**\n\n   - Tailscale은 자동 HTTPS 인증서 제공\n   - 기타 배포의 경우 Let's Encrypt와 함께 리버스 프록시(Nginx/Caddy) 사용\n\n3. **공개 인터넷보다 VPN 선호**\n\n   - Tailscale Serve(VPN 전용)가 Funnel(공개)보다 안전\n   - VPN 내에서는 인증이 선택 사항이지만 공개 접근에는 필수\n\n4. **접근 모니터링**\n\n   ```bash\n   # 무단 접근 시도 확인\n   docker compose logs mcp-server | grep \"Unauthorized\"\n   ```\n\n5. **네트워크 격리**\n   - ChromaDB를 프라이빗 네트워크에 유지\n   - MCP 서버만 공개 인터넷에 노출\n\n---\n\n## 테스트\n\n### 로컬 테스트\n\n```bash\n# 헬스 체크\ncurl http://localhost:3000/health\n\n# MCP 도구 목록\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'\n\n# ChromaDB heartbeat\ncurl http://localhost:3000/api/v2/heartbeat\n```\n\n### 원격 테스트 (인증 포함)\n\n```bash\n# MCP 엔드포인트 (Bearer 토큰)\ncurl -X POST https://your-server.com/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}'\n\n# MCP 엔드포인트 (Query parameter)\ncurl -X POST \"https://your-server.com/mcp?apiKey=YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}'\n\n# ChromaDB REST API\ncurl https://your-server.com/api/v2/heartbeat \\\n  -H \"X-Chroma-Token: YOUR_TOKEN\"\n\n# Swagger UI (브라우저)\nhttps://your-server.com/docs?apiKey=YOUR_TOKEN\n```\n\n---\n\n## 문제 해결\n\n### ChromaDB 연결 실패\n\n```bash\n# ChromaDB가 실행 중인지 확인\ncurl http://localhost:8000/api/v2/heartbeat\n\n# Docker로 ChromaDB 시작\ndocker run -d -p 8000:8000 chromadb/chroma:latest\n\n# MCP 서버 로그 확인\ndocker compose logs mcp-server\n```\n\n### MCP 서버가 응답하지 않음\n\n```bash\n# 로그 확인\ndocker compose logs mcp-server\n\n# 포트 충돌 확인\nlsof -i :3000\n\n# 서비스 재시작\ndocker compose restart\n```\n\n### Claude Desktop 연결 문제\n\n1. Claude Desktop 재시작\n2. URL에 `/mcp` 경로가 포함되어 있는지 확인\n3. 전송 타입이 `streamableHttp`인지 확인 (`sse` 아님)\n4. 인증이 활성화된 경우 인증 토큰 확인\n5. Custom Connector용: Tailscale Funnel이 활성화되어 있는지 확인\n\n### 로컬 네트워크에서 TLS Handshake 타임아웃\n\n서버와 같은 로컬 네트워크에서 Tailscale Funnel HTTPS로 접속하는 경우:\n\n**문제**: 같은 네트워크에서 `https://your-server.ts.net` 접속 시 TLS handshake 타임아웃 발생.\n\n**원인**: Tailscale Funnel은 같은 LAN의 클라이언트가 공개 Funnel 도메인으로 접속할 때 TLS 종료 처리에 문제가 있음.\n\n**해결**: Tailscale HTTPS 대신 로컬 네트워크 직접 연결 사용:\n\n```bash\n# 기존 설정 제거\nclaude mcp remove chromadb\n\n# 로컬 IP 주소로 추가\nclaude mcp add chromadb --transport http \\\n  http://192.168.x.x:8080/mcp \\\n  --header \"Authorization: Bearer YOUR_TOKEN\"\n\n# 또는 DNS가 동작하면 호스트명 사용\nclaude mcp add chromadb --transport http \\\n  http://server-hostname:8080/mcp \\\n  --header \"Authorization: Bearer YOUR_TOKEN\"\n```\n\n**확인**:\n```bash\n# 로컬 네트워크 연결 테스트\ncurl http://192.168.x.x:8080/health\n\n# 응답: {\"status\":\"ok\",\"service\":\"chroma-remote-mcp\",...}\n```\n\n**참고**: 외부 클라이언트는 계속 Tailscale Funnel HTTPS를 사용하면 됩니다. 이 문제는 서버와 같은 LAN의 클라이언트에만 해당됩니다.\n\n### 인증 오류 (401)\n\n```bash\n# MCP_AUTH_TOKEN이 설정되어 있는지 확인\ndocker compose exec mcp-server env | grep MCP_AUTH_TOKEN\n\n# 토큰 없이 테스트 (401 실패 예상)\ncurl -X POST https://your-server.com/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}'\n\n# 올바른 토큰으로 테스트 (성공 예상)\ncurl -X POST https://your-server.com/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}'\n```\n\n---\n\n## 개발\n\n### 소스에서 빌드\n\n```bash\n# 저장소 클론\ngit clone https://github.com/meloncafe/chromadb-remote-mcp.git\ncd chromadb-remote-mcp\n\n# 의존성 설치\nyarn install\n\n# 개발 모드 (자동 재로드)\nyarn dev\n\n# TypeScript 빌드\nyarn build\n\n# 타입 체크\nyarn type-check\n```\n\n### 테스팅\n\n프로젝트는 Docker 기반 E2E 검증을 포함한 통합 테스트를 제공합니다:\n\n```bash\n# 모든 테스트 실행 (서비스 시작, 테스트 실행, 정리)\nyarn test\n\n# 테스트 실행 후 컨테이너 유지 (디버깅용)\nyarn test:keep\n\n# 옵션이 있는 수동 테스트 스크립트\n./scripts/test.sh --help\n```\n\n**통합 테스트 커버리지:**\n\n- ✅ 헬스 체크 엔드포인트\n- ✅ 인증 (Bearer 토큰, X-Chroma-Token, 쿼리 파라미터)\n- ✅ MCP 프로토콜 (tools/list, tools/call)\n- ✅ ChromaDB REST API 프록시\n- ✅ 컬렉션 CRUD 작업\n- ✅ Rate limiting\n- ✅ 비인증 접근 처리\n\n**단위 테스트:**\n\n```bash\n# 단위 테스트 실행\nyarn test:unit\n\n# watch 모드로 실행\nyarn test:unit:watch\n\n# 커버리지와 함께 실행\nyarn test:unit:coverage\n\n# 모든 테스트 실행 (단위 + 통합)\nyarn test:all\n```\n\n**단위 테스트 커버리지:**\n\n- ✅ 인증 유틸리티 (timing-safe 비교, 버퍼 작업)\n- ✅ 입력 검증 (컬렉션 이름, 문서 ID, 메타데이터)\n- ✅ 데이터 처리 (응답 포맷팅, JSON 직렬화)\n- ✅ 에러 메시지 포맷팅\n\n자세한 테스팅 전략은 `__tests__/README.md`를 참조하세요.\n\n### 코드 품질 및 커버리지\n\n이 프로젝트는 코드 커버리지 추적 및 테스트 분석을 위해 [Codecov](https://codecov.io/gh/meloncafe/chromadb-remote-mcp)를 사용합니다.\n\n### Docker 개발\n\n#### 로컬 빌드 및 테스트\n\n```bash\n# 로컬 테스트용 빌드 (단일 플랫폼, Docker에 로드)\nyarn docker:build:local\n\n# 또는 스크립트 직접 사용\n./scripts/build.sh --platform linux/amd64 --load\n\n# 빌드된 이미지 테스트\ndocker run -p 3000:3000 \\\n  -e MCP_AUTH_TOKEN=test123 \\\n  devsaurus/chromadb-remote-mcp:latest\n```\n\n#### 멀티 플랫폼 빌드\n\n```bash\n# 모든 플랫폼용 빌드 (amd64, arm64)\nyarn docker:build\n\n# 커스텀 버전으로 빌드\n./scripts/build.sh --version 1.2.3\n\n# 커스텀 저장소로 빌드\n./scripts/build.sh --repo myuser/my-mcp --version dev\n```\n\n#### Docker Hub에 푸시\n\n```bash\n# latest 태그 푸시\nyarn docker:push\n\n# 특정 버전 푸시\nVERSION=1.2.3 yarn docker:push\n\n# 또는 스크립트 직접 사용\n./scripts/build.sh --version 1.2.3 --push\n\n# 커스텀 저장소 사용\nDOCKER_REPO=myuser/my-mcp ./scripts/build.sh --version 1.2.3 --push\n```\n\n**Docker 스크립트용 환경 변수:**\n\n```bash\nexport DOCKER_REPO=myuser/my-mcp       # Docker 저장소\nexport VERSION=1.2.3                    # 이미지 버전 태그\nexport DOCKER_USERNAME=myuser           # 푸시 인증용\nexport DOCKER_PASSWORD=mytoken          # Docker Hub 토큰\n```\n\n### 개발 스크립트\n\n모든 개발 스크립트는 `scripts/` 디렉토리에 있습니다:\n\n| 스크립트     | 목적                       | 사용법                      |\n| ------------ | -------------------------- | --------------------------- |\n| `build.sh`   | Docker 이미지 빌드 및 푸시 | `./scripts/build.sh --help` |\n| `test.sh`    | 통합 테스트 실행           | `./scripts/test.sh --help`  |\n| `install.sh` | 원 커맨드 설치             | `curl ... \\| bash`          |\n\n**빠른 개발 워크플로:**\n\n```bash\n# 1. 코드 변경\nvim src/index.ts\n\n# 2. 로컬 테스트\nyarn dev\n\n# 3. 통합 테스트 실행\nyarn test\n\n# 4. Docker 이미지 빌드\nyarn docker:build:local\n\n# 5. Docker 이미지 테스트\ndocker-compose up\n\n# 6. 모든 것이 정상이면 멀티 플랫폼 빌드 및 푸시\n./scripts/build.sh --version 1.2.3 --push\n```\n\n### 프로젝트 구조\n\n```\nchromadb-remote-mcp/\n├── .github/\n│   ├── ISSUE_TEMPLATE/       # GitHub 이슈 템플릿\n│   └── workflows/            # GitHub Actions (publish-release, security-scan, chromadb-version-check)\n├── scripts/\n│   ├── build.sh             # Docker 빌드 및 푸시 스크립트 (멀티 플랫폼)\n│   ├── test.sh              # 통합 테스트 러너\n│   └── install.sh           # 원 커맨드 설치\n├── src/\n│   ├── index.ts             # 메인 서버 진입점\n│   ├── chroma-tools.ts      # MCP 도구 정의 및 핸들러\n│   └── types.ts             # TypeScript 타입 정의\n├── docker-compose.yml       # 프로덕션 (사전 빌드된 이미지)\n├── docker-compose.dev.yml   # 개발 (소스에서 빌드)\n├── Dockerfile               # MCP 서버 Docker 이미지\n├── .env.example             # 환경 변수 템플릿\n├── package.json             # Node.js 의존성\n├── tsconfig.json            # TypeScript 설정\n├── SECURITY.md              # 보안 정책\n├── CONTRIBUTING.md          # 기여 가이드라인\n├── CODE_OF_CONDUCT.md       # 행동 강령\n├── CHANGELOG.md             # 버전 히스토리\n└── LICENSE                  # MIT 라이선스\n```\n\n---\n\n## 기여\n\n기여를 환영합니다! 이슈와 풀 리퀘스트를 자유롭게 제출해 주세요.\n\n1. 저장소 포크\n2. 기능 브랜치 생성 (`git checkout -b feature/amazing-feature`)\n3. 변경사항 커밋 (`git commit -m 'Add amazing feature'`)\n4. 브랜치에 푸시 (`git push origin feature/amazing-feature`)\n5. Pull Request 열기\n\n---\n\n## 라이선스\n\n[MIT License](LICENSE)\n\n---\n\n## 참고 자료\n\n- [MCP 스펙](https://modelcontextprotocol.io/specification/2025-06-18/)\n- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n- [ChromaDB 문서](https://docs.trychroma.com/)\n- [Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve/)\n- [Tailscale Funnel](https://tailscale.com/kb/1223/funnel)\n- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)\n\n---\n\n## 지원\n\n문제가 발생하거나 질문이 있으시면 [이슈를 열어주세요](https://github.com/meloncafe/chromadb-remote-mcp/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeloncafe%2Fchromadb-remote-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeloncafe%2Fchromadb-remote-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeloncafe%2Fchromadb-remote-mcp/lists"}