# MCP — Claude / Cursor 연결
AstroWay의 MCP 서버는 **모든 {siteMeta.endpoints} 엔드포인트**를 AI 에이전트가 사용할 수 있는 도구로 노출합니다. 두 가지 모드가 있으며, 모두 MCP 호환 클라이언트에서 기본적으로 지원됩니다.
| 모드 | URL / 명령 | 선택 기준 |
|---|---|---|
| **Hosted HTTP** | `https://mcp.astroway.info/mcp` | 브라우저의 Claude Web (claude.ai), Claude Desktop / Cursor / Code 초보자, npm 없이 사용하거나 zero-install을 원할 때 |
| **Stdio (npm)** | `npx @astroway/mcp` | Cursor 고급 사용자, 로컬 개발, 프라이버시 보호 (키가 절대 서버로 전송되지 않음), 오프라인 환경 |
Hosted 엔드포인트와 npm 패키지는 **동일한 도구 카탈로그**를 사용합니다(하나의 `/v1/openapi.json`에서 생성됨). 인증: 동일한 `aw_test_*` / `aw_live_*` API 키 — hosted는 `Authorization: Bearer …` 헤더로, stdio는 `ASTROWAY_API_KEY` 환경 변수로 전송됩니다.
출처: [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp) · npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) · hosted: [mcp.astroway.info/health](https://mcp.astroway.info/health)
## Hosted (`mcp.astroway.info`) — zero install
npm 없이 빠르게 시작하세요. 클라이언트를 선택하고, [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up)에서 키를 받으세요(월 **10,000 크레딧 무료**).
버튼을 클릭하면 Cursor가 열리고, 확인을 요청한 후 자동으로 설정을 추가합니다:
Cursor에서 설치 →
:::caution[필수 2단계 — 그렇지 않으면 작동하지 않음]
Cursor는 deeplink로 비밀을 삽입할 수 없습니다. `~/.cursor/mcp.json`에 `Bearer YOUR_API_KEY`라는 리터럴이 기록되며, 서버는 `403 invalid_format`을 반환합니다.
**버튼 클릭 후:**
1. **Cursor 설정**(⚙️ 오른쪽 상단) → **도구 & MCP** → 목록에서 `astroway-hosted`를 찾습니다.
2. 서버 옆 세 점(`⋯`)을 클릭 → **구성 편집**.
3. `Authorization` 필드에서 `Bearer YOUR_API_KEY`를 `Bearer aw_test_…`(또는 `aw_live_…`)로 바꿉니다. 이 키는 [대시보드](https://api.astroway.info/dashboard/keys)에서 가져옵니다.
4. 저장 → MCP 목록을 다시 열어 상태가 **활성화** + 초록색 점 + `630 tools enabled` 카운터인지 확인합니다.
또는 파일을 직접 편집할 수도 있습니다: `~/.cursor/mcp.json`(`headers.Authorization`).
:::
JSON 편집 없이 사용하세요. Claude Desktop의 모든 채팅에서:
1. 입력 필드 왼쪽에 있는 **`+`**를 클릭 → 메뉴에서 **"Add connector"**를 선택합니다.
2. 대화 상자에서 **"Add custom connector"**를 클릭합니다.
3. **Name:** `astroway-hosted`
4. **URL:** `https://mcp.astroway.info/mcp`
5. **"Advanced settings"**를 펼치고 **"Custom headers"**에 다음을 추가합니다:
- **Key:** `Authorization`
- **Value:** `Bearer aw_live_...`(당신의 키)
6. **Add** → Connectors 목록에서 `astroway-hosted`를 찾고 스위치를 켭니다.
Claude Desktop을 재시작할 **필요 없습니다**. 새 채팅에서 `+`를 누르면 Connectors에 `astroway-hosted`가 나타나며, 모든 630개 도구 + 12개 프롬프트 + 14개 리소스가 포함됩니다.
Cline / Continue / Windsurf 또는 오래된 버전의 Claude Desktop / Cursor용:
```json
{
"mcpServers": {
"astroway-hosted": {
"url": "https://mcp.astroway.info/mcp",
"headers": {
"Authorization": "Bearer aw_live_..."
}
}
}
}
```
구성 파일 경로:
- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
- **Cursor:** `~/.cursor/mcp.json`(전역) 또는 `.cursor/mcp.json`(워크스페이스)
- **Cline (VS Code):** `.cline/mcp.json`(워크스페이스)
- **Continue:** `~/.continue/config.json`(`mcpServers` 블록)
- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`
수정 후 클라이언트를 완전히 재시작하세요(Cmd+Q → 다시 열기).
### 확인
```bash
curl https://mcp.astroway.info/health
# {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"}
```
클라이언트에서 *"List 5 AstroWay tool names from astroway-hosted"*라고 요청하세요. `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full` 등의 이름이 반환되어야 합니다.
### Rate limits
Hosted 엔드포인트는 3단계 제한으로 보호됩니다: Cloudflare DDoS 보호 + nginx `120 req/min/IP` + 인메모리 버킷 `60/60s/(IP+키)`. 실제 MCP 클라이언트(Claude Desktop, Cursor)는 이런 제한에 도달하지 않습니다 — burst 요청을 하지 않기 때문입니다. 자동화나 CI에서 **매분 120회 이상의 요청**이 필요하다면 **stdio** 모드를 사용하세요(여기서는 제한이 없으며, `api.astroway.info/v1/*`로 직접 요청하여 자신의 요금제 rate-limit만 적용됩니다).
### `mcp.astroway.info`가 일시적으로 사용할 수 없을 때
Hosted 엔드포인트가 5xx 오류를 반환하면 MCP 클라이언트는 `tools/list`에서 오류를 확인합니다. 이는 **stdio 클라이언트에 영향을 주지 않습니다** — 이들은 로컬 npm 패키지를 실행하며, hosted 중간 계층 없이 직접 `api.astroway.info/v1/*`로 요청합니다.
**중요 통합을 위한 폴백:** hosted가 `tools/list`에 응답하지 않을 경우 자동으로 대체할 **두 번째 MCP 서버**를 구성에 추가하세요:
```json
{
"mcpServers": {
"astroway": {
"url": "https://mcp.astroway.info/mcp",
"headers": { "Authorization": "Bearer aw_live_..." }
},
"astroway-fallback": {
"command": "npx",
"args": ["-y", "@astroway/mcp"],
"env": { "ASTROWAY_API_KEY": "aw_live_..." }
}
}
}
```
Hosted 엔드포인트의 실제 가동 시간은 [status.astroway.info](https://status.astroway.info)에서 확인할 수 있습니다. 5분 이상의 장애 발생 시 5영업일 이내에 postmortem을 공개합니다([/sla/](/sla/) 참고).
## Stdio (npm) — 로컬 개발용
[`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp)는 로컬에서 서브프로세스로 실행되는 npm 패키지입니다. Claude Desktop, Cursor 등 모든 MCP 호환 클라이언트와 네이티브하게 통합됩니다.
## 작동 방식
도구 목록은 **빌드 시점**에 live OpenAPI 사양([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json))에서 생성됩니다. 패키지 릴리스 시 모든 새로운 엔드포인트가 자동으로 반영됩니다 — 수동으로 관리할 필요가 없습니다.
각 엔드포인트는 다음과 같은 도구가 됩니다:
- `tools/list`는 입력 스키마와 예제 요청 본문을 포함한 설명을 반환합니다.
- `tools/call`은 HTTP POST를 `https://api.astroway.info/v1/`로 전송하며, 당신의 `ASTROWAY_API_KEY`를 사용합니다.
- 응답은 에이전트에게 구조화된 JSON으로 반환됩니다.
각 릴리스는 SLSA provenance([Sigstore-증명됨](https://search.sigstore.dev/))로도 제공됩니다 — npm 패키지가 공개 저장소의 커밋에서 빌드되었음을 보장합니다.
## 설치
### Claude Desktop (macOS)
`~/Library/Application Support/Claude/claude_desktop_config.json`에 다음을 추가합니다:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["-y", "@astroway/mcp"],
"env": {
"ASTROWAY_API_KEY": "aw_live_..."
}
}
}
}
```
Claude Desktop을 재시작하세요. 채팅 아래 바에 🛠️ 아이콘과 로드된 도구 수가 표시됩니다.
### Cursor
`~/.cursor/mcp.json`에 다음을 추가합니다:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["-y", "@astroway/mcp"],
"env": { "ASTROWAY_API_KEY": "aw_live_..." }
}
}
}
```
### Cline / Continue / Windsurf / Copilot / VS Code MCP
모든 MCP 호환 클라이언트에서 동일한 `npx @astroway/mcp` 명령이 작동합니다. 구성은 동일하며 파일 경만 다릅니다:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["-y", "@astroway/mcp"],
"env": { "ASTROWAY_API_KEY": "aw_live_..." }
}
}
}
```
| 클라이언트 | 구성 파일 경로 |
|---|---|
| **Cline** (VS Code) | 워크스페이스 루트의 `.cline/mcp.json` |
| **Continue** | `~/.continue/config.json`(`mcpServers` 하위) |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **GitHub Copilot Chat (VS Code)** | 미리보기 플래그 → 워크스페이스의 `mcp.json` |
| **VS Code MCP 확장** | `~/.vscode/mcp.json` |
### 기타 MCP 클라이언트
stdio 서버로 실행합니다:
```bash
ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp
```
## Privacy — v1.0.0+부터
이 MCP 서버는 **당신이 직접 수행하라는 API 호출 외에는 AstroWay로 아무것도 전송하지 않습니다**. 기본적으로 텔레메트리나 분석, opt-in/opt-out 스위치도 없습니다 — 완전한 비공개입니다.
요청에는 AstroWay 백엔드가 MCP 트래픽을 직접 HTTP 요청과 구분할 수 있도록 두 개의 식별 헤더가 포함됩니다:
- `User-Agent: astroway-mcp/ (Node/)`
- `X-Astroway-Channel: mcp`
이들 헤더에는 세션 ID, 머신 핑거프린트 또는 개인정보가 포함되지 않습니다. 표준 `User-Agent` 의미 체계에 따라 전송되는 정보입니다 — 모든 CLI 도구가 подобную 정보를 전송합니다.
## Subset registration — v1.0.0+부터
카탈로그 전체가 아니라 일부만 사용할 경우, LLM의 컨텍스트 창을 절약하기 위해 하위 집합을 등록하세요:
```jsonc
{
"env": {
"ASTROWAY_API_KEY": "aw_live_...",
"ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // 해당 접두사만
"ASTROWAY_READONLY": "1" // ai/horoscope/reports 건너뛰기 (LLM 기반, 크레딧 소모)
}
}
```
주요 그룹: `western`, `vedic`, `tarot`, `numerology`, `hd`(Human Design), `relational`(synastry/composite/davison), `prognostics`(transits/progressions/returns), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. 전체 목록을 보려면 `npx @astroway/mcp --list-tools`를 실행하세요.
`ASTROWAY_READONLY=1`은 내부적으로 LLM을 호출하는 세 그룹(`ai`, `horoscope`, `reports`)을 건너뜁니다 — 텍스트 생성에 크레딧이 소모되지 않는 순수한 수학적 계산만 원할 때 유용합니다.
## Stability commitment — v1.0.0+부터
- **세션 동안 카탈로그가 고정됩니다.** 624개 도구, 12개 프롬프트, 14개 리소스가 npm 패키지에 빌드 시점에 포함되며, 연결 중 변경되지 않습니다. 클라이언트가 `tools/list`를 캐시하면 세션 내내 유효합니다.
- **v1.x 범위 내에서는 도구 식별자가 안정적입니다.** `astroway__` 형식의 이름은 `v1.x` 내에서는 마이너 버전 업데이트 없이 삭제되거나 이름이 바뀌지 않습니다(단, `CHANGELOG.md`에 deprecation 노트가 게시됩니다).
- **v1.x 범위 내에서는 도구 입력 형태가 마이너 버전까지 안정적입니다.** 패치에서 regex, range, enum이 추가됩니다. 필수 필드의 추가가 필요한 경우 마이너 버전 업그레이드가 필요합니다.
- **카탈로그 새로고침은 재설치로 진행됩니다.** `npm i -g @astroway/mcp@latest`(또는 구성 파일의 `npx -y @astroway/mcp`)를 통해 다음 시작 시 최신 카탈로그를 가져옵니다.
## 프롬프트 예시
연결 후 AI에게 다음을 요청하세요:
### natal chart
> 1990년 3월 15일 14:30 Киев 출생의 natal chart를 계산해줘. 태양, 달, 상승점, 그리고 밀접한 aspects를 찾아줘.
Claude가 `chart` 도구를 호출하여 매개변수를 전달하면 구조화된 JSON을 받고, 이를 바탕으로 chart를 설명합니다.
### transits
> 2027년 한 해 동안 느리게 움직이는 행성의 주요 transit이 내 natal chart에 어떤 영향을 미칠까?
Claude가 두 개의 도구 호출을 수행합니다: 먼저 `transits`(현재 스냅샷), 그 다음 `transit-calendar`(기간). 트렌드를 해석합니다.
### Vedic Mahadasha
> 1985년 7월 22일 06:45 뭄바이 출생자의 Vimshottari Mahadasha를 계산해줘. 현재 어떤 기간에 있는 거야?
`vedic/dashas/vimshottari/maha` 도구를 통해 — 현재 기간의 정확한 UTC 타임스탬프를 반환합니다.
### synastry
> 두 chart 비교: A — 1988년 6월 10일 09:15 런던, B — 1991년 11월 22일 22:40 베를린. 가장 강력한 cross-aspects는 뭐야?
`synastry` 도구는 두 개의 `chart` 블록과 호환성 점수 해석을 포함합니다.
### tarot
> 라이더-웨이트-스미스 카드 3장 뽑기: 과거 — 현재 — 미래. 질문: "새 직장을 받아들여야 할까?". 시드 = 42.
`tarot/rider-waite/spread`는 재현 가능한 시드로 고정됩니다.
## 모든 도구 목록
연결 후 Claude에게 다음을 요청하세요:
> astroway-도구 전체를 나열해줘.
또는 명령줄에서:
```bash
ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (stdio 서버를 실행; 프로토콜 도구 목록 호출은 MCP 클라이언트에서 전송됨)
```
## 구성
| 변수 | 기본값 | 설명 | 버전 |
|---|---|---|---|
| `ASTROWAY_API_KEY` | *(필수)* | 라이브: `aw_live_...`. 샌드박스: `aw_test_...`. | 0.1.0 |
| `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | 자체 호스팅/스테이징 환경 오버라이드. | 0.1.0 |
| `ASTROWAY_TOOL_GROUPS` | *(모든 그룹)* | 카탈로그 제한을 위한 콤마로 구분된 접두사(`western,vedic,relational`). | 1.0.0 |
| `ASTROWAY_READONLY` | `0` | `1`은 LLM 기반 그룹(`ai`, `horoscope`, `reports`)을 건너뜁니다. | 1.0.0 |
| `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — stderr 로깅 수준. | 0.8.0 |
| `LOG_FILE` | *(파일 쓰기 안 함)* | 로그를 덤프할 파일 경로. | 0.8.0 |
| `MCP_FLAT_TOOLS` | `0` | `1`은 v0.9 이전 플랫 이름(`astroway_western_chart` 대신 `chart`)을 반환합니다. 레거시. | 0.9.0 |
## 왜 MCP를 사용할까? 직접 통합이 아니라
일반 LLM(grounding 없이)은 *"7월 somewhere에 토성이 너의 목성과의 삼분각을 이룰 거야"*라고 말할 뿐, 정확한 날짜는 ±15일 오차로 부정확합니다. **MCP 에이전트**는 `tool_use POST /v1/transits`를 호출하고, **Swiss Ephemeris를 기반으로 초 단위의 UTC 타임스탬프**를 반환합니다.
LLM의 장점이 아니라 **실제 수학 계산이 보장된다는 점**이 핵심입니다.
## 패키지 배포
- **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway)
- **mcpservers.org:** 2026년 5월 기준 승인 대기 중
- **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972)
## 링크
- 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp)
- 📘 API 문서: [/docs/api/](/docs/api/)
- 🔑 가입: [/dashboard/sign-up](/dashboard/sign-up)
- 💰 요금제: [/pricing/](/pricing/)
- 🌐 공개 저장소 (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)