콘텐츠로 이동
AstroWay/api v2.102.11 · ko
모든 시스템 정상 작동 중

MCP — Claude / Cursor 연결

AstroWay의 MCP 서버는 모든 723 엔드포인트를 AI 에이전트가 사용할 수 있는 도구로 노출합니다. 두 가지 모드가 있으며, 모두 MCP 호환 클라이언트에서 기본적으로 지원됩니다.

모드URL / 명령선택 기준
Hosted HTTPhttps://mcp.astroway.info/mcp브라우저의 Claude Web (claude.ai), Claude Desktop / Cursor / Code 초보자, npm 없이 사용하거나 zero-install을 원할 때
Stdio (npm)npx @astroway/mcpCursor 고급 사용자, 로컬 개발, 프라이버시 보호 (키가 절대 서버로 전송되지 않음), 오프라인 환경

Hosted 엔드포인트와 npm 패키지는 동일한 도구 카탈로그를 사용합니다(하나의 /v1/openapi.json에서 생성됨). 인증: 동일한 aw_test_* / aw_live_* API 키 — hosted는 Authorization: Bearer … 헤더로, stdio는 ASTROWAY_API_KEY 환경 변수로 전송됩니다.

출처: github.com/astroway/astroway-mcp · npm: npmjs.com/package/@astroway/mcp · hosted: mcp.astroway.info/health

Hosted (mcp.astroway.info) — zero install

섹션 제목: “Hosted (mcp.astroway.info) — zero install”

npm 없이 빠르게 시작하세요. 클라이언트를 선택하고, api.astroway.info/dashboard/sign-up에서 키를 받으세요(월 10,000 크레딧 무료).

버튼을 클릭하면 Cursor가 열리고, 확인을 요청한 후 자동으로 설정을 추가합니다:

Cursor에서 설치 →

확인

섹션 제목: “확인”
Terminal window
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

섹션 제목: “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가 일시적으로 사용할 수 없을 때

섹션 제목: “mcp.astroway.info가 일시적으로 사용할 수 없을 때”

Hosted 엔드포인트가 5xx 오류를 반환하면 MCP 클라이언트는 tools/list에서 오류를 확인합니다. 이는 stdio 클라이언트에 영향을 주지 않습니다 — 이들은 로컬 npm 패키지를 실행하며, hosted 중간 계층 없이 직접 api.astroway.info/v1/*로 요청합니다.

중요 통합을 위한 폴백: hosted가 tools/list에 응답하지 않을 경우 자동으로 대체할 두 번째 MCP 서버를 구성에 추가하세요:

{
  "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에서 확인할 수 있습니다. 5분 이상의 장애 발생 시 5영업일 이내에 postmortem을 공개합니다(/sla/ 참고).

Stdio (npm) — 로컬 개발용

섹션 제목: “Stdio (npm) — 로컬 개발용”

@astroway/mcp는 로컬에서 서브프로세스로 실행되는 npm 패키지입니다. Claude Desktop, Cursor 등 모든 MCP 호환 클라이언트와 네이티브하게 통합됩니다.

작동 방식

섹션 제목: “작동 방식”

도구 목록은 빌드 시점에 live OpenAPI 사양(api.astroway.info/v1/openapi.json)에서 생성됩니다. 패키지 릴리스 시 모든 새로운 엔드포인트가 자동으로 반영됩니다 — 수동으로 관리할 필요가 없습니다.

각 엔드포인트는 다음과 같은 도구가 됩니다:

  • tools/list는 입력 스키마와 예제 요청 본문을 포함한 설명을 반환합니다.
  • tools/call은 HTTP POST를 https://api.astroway.info/v1/<path>로 전송하며, 당신의 ASTROWAY_API_KEY를 사용합니다.
  • 응답은 에이전트에게 구조화된 JSON으로 반환됩니다.

각 릴리스는 SLSA provenance(Sigstore-증명됨)로도 제공됩니다 — npm 패키지가 공개 저장소의 커밋에서 빌드되었음을 보장합니다.

설치

섹션 제목: “설치”

Claude Desktop (macOS)

섹션 제목: “Claude Desktop (macOS)”

~/Library/Application Support/Claude/claude_desktop_config.json에 다음을 추가합니다:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": {
        "ASTROWAY_API_KEY": "aw_live_..."
      }
    }
  }
}

Claude Desktop을 재시작하세요. 채팅 아래 바에 🛠️ 아이콘과 로드된 도구 수가 표시됩니다.

Cursor

섹션 제목: “Cursor”

~/.cursor/mcp.json에 다음을 추가합니다:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

Cline / Continue / Windsurf / Copilot / VS Code MCP

섹션 제목: “Cline / Continue / Windsurf / Copilot / VS Code MCP”

모든 MCP 호환 클라이언트에서 동일한 npx @astroway/mcp 명령이 작동합니다. 구성은 동일하며 파일 경만 다릅니다:

{
  "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 클라이언트

섹션 제목: “기타 MCP 클라이언트”

stdio 서버로 실행합니다:

Terminal window
ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Privacy — v1.0.0+부터

섹션 제목: “Privacy — v1.0.0+부터”

이 MCP 서버는 당신이 직접 수행하라는 API 호출 외에는 AstroWay로 아무것도 전송하지 않습니다. 기본적으로 텔레메트리나 분석, opt-in/opt-out 스위치도 없습니다 — 완전한 비공개입니다.

요청에는 AstroWay 백엔드가 MCP 트래픽을 직접 HTTP 요청과 구분할 수 있도록 두 개의 식별 헤더가 포함됩니다:

  • User-Agent: astroway-mcp/<version> (Node/<node-version>)
  • X-Astroway-Channel: mcp

이들 헤더에는 세션 ID, 머신 핑거프린트 또는 개인정보가 포함되지 않습니다. 표준 User-Agent 의미 체계에 따라 전송되는 정보입니다 — 모든 CLI 도구가 подобную 정보를 전송합니다.

Subset registration — v1.0.0+부터

섹션 제목: “Subset registration — v1.0.0+부터”

카탈로그 전체가 아니라 일부만 사용할 경우, LLM의 컨텍스트 창을 절약하기 위해 하위 집합을 등록하세요:

{
  "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+부터

섹션 제목: “Stability commitment — v1.0.0+부터”
  • 세션 동안 카탈로그가 고정됩니다. 624개 도구, 12개 프롬프트, 14개 리소스가 npm 패키지에 빌드 시점에 포함되며, 연결 중 변경되지 않습니다. 클라이언트가 tools/list를 캐시하면 세션 내내 유효합니다.
  • v1.x 범위 내에서는 도구 식별자가 안정적입니다. astroway_<group>_<tool> 형식의 이름은 v1.x 내에서는 마이너 버전 업데이트 없이 삭제되거나 이름이 바뀌지 않습니다(단, CHANGELOG.md에 deprecation 노트가 게시됩니다).
  • v1.x 범위 내에서는 도구 입력 형태가 마이너 버전까지 안정적입니다. 패치에서 regex, range, enum이 추가됩니다. 필수 필드의 추가가 필요한 경우 마이너 버전 업그레이드가 필요합니다.
  • 카탈로그 새로고침은 재설치로 진행됩니다. npm i -g @astroway/mcp@latest(또는 구성 파일의 npx -y @astroway/mcp)를 통해 다음 시작 시 최신 카탈로그를 가져옵니다.

프롬프트 예시

섹션 제목: “프롬프트 예시”

연결 후 AI에게 다음을 요청하세요:

natal chart

섹션 제목: “natal chart”

1990년 3월 15일 14:30 Киев 출생의 natal chart를 계산해줘. 태양, 달, 상승점, 그리고 밀접한 aspects를 찾아줘.

Claude가 chart 도구를 호출하여 매개변수를 전달하면 구조화된 JSON을 받고, 이를 바탕으로 chart를 설명합니다.

transits

섹션 제목: “transits”

2027년 한 해 동안 느리게 움직이는 행성의 주요 transit이 내 natal chart에 어떤 영향을 미칠까?

Claude가 두 개의 도구 호출을 수행합니다: 먼저 transits(현재 스냅샷), 그 다음 transit-calendar(기간). 트렌드를 해석합니다.

Vedic Mahadasha

섹션 제목: “Vedic Mahadasha”

1985년 7월 22일 06:45 뭄바이 출생자의 Vimshottari Mahadasha를 계산해줘. 현재 어떤 기간에 있는 거야?

vedic/dashas/vimshottari/maha 도구를 통해 — 현재 기간의 정확한 UTC 타임스탬프를 반환합니다.

synastry

섹션 제목: “synastry”

두 chart 비교: A — 1988년 6월 10일 09:15 런던, B — 1991년 11월 22일 22:40 베를린. 가장 강력한 cross-aspects는 뭐야?

synastry 도구는 두 개의 chart 블록과 호환성 점수 해석을 포함합니다.

tarot

섹션 제목: “tarot”

라이더-웨이트-스미스 카드 3장 뽑기: 과거 — 현재 — 미래. 질문: “새 직장을 받아들여야 할까?”. 시드 = 42.

tarot/rider-waite/spread는 재현 가능한 시드로 고정됩니다.

모든 도구 목록

섹션 제목: “모든 도구 목록”

연결 후 Claude에게 다음을 요청하세요:

astroway-도구 전체를 나열해줘.

또는 명령줄에서:

Terminal window
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_URLhttps://api.astroway.info/v1자체 호스팅/스테이징 환경 오버라이드.0.1.0
ASTROWAY_TOOL_GROUPS(모든 그룹)카탈로그 제한을 위한 콤마로 구분된 접두사(western,vedic,relational).1.0.0
ASTROWAY_READONLY01은 LLM 기반 그룹(ai, horoscope, reports)을 건너뜁니다.1.0.0
LOG_LEVELerrorsilent/error/warn/info/debug — stderr 로깅 수준.0.8.0
LOG_FILE(파일 쓰기 안 함)로그를 덤프할 파일 경로.0.8.0
MCP_FLAT_TOOLS01은 v0.9 이전 플랫 이름(astroway_western_chart 대신 chart)을 반환합니다. 레거시.0.9.0

왜 MCP를 사용할까? 직접 통합이 아니라

섹션 제목: “왜 MCP를 사용할까? 직접 통합이 아니라”

일반 LLM(grounding 없이)은 *“7월 somewhere에 토성이 너의 목성과의 삼분각을 이룰 거야”*라고 말할 뿐, 정확한 날짜는 ±15일 오차로 부정확합니다. MCP 에이전트는 tool_use POST /v1/transits를 호출하고, Swiss Ephemeris를 기반으로 초 단위의 UTC 타임스탬프를 반환합니다.

LLM의 장점이 아니라 실제 수학 계산이 보장된다는 점이 핵심입니다.

패키지 배포

섹션 제목: “패키지 배포”

링크

섹션 제목: “링크”
도움이 되었나요?
Запропонувати правку

마지막 업데이트: