MCP - Claude / Cursor 연결

AstroWay Model Context Protocol 서버는 AI 에이전트용 도구로 모든 771 엔드포인트를 노출합니다. 두 가지 모드 모두 모든 MCP 호환 클라이언트에서 기본적으로 지원됩니다.

모드	URL / 명령	선택 시기
Hosted HTTP	`https://mcp.astroway.info/mcp`	Claude Web (브라우저의 claude.ai), npm 없이 Claude Desktop / Cursor / Code 초보자, 또는 제로 설치를 원할 때
Stdio (npm)	`npx @astroway/mcp`	Cursor 파워 유저, 로컬 개발, 개인 정보 보호에 민감한 경우 (키가 당신의 머신을 떠나지 않음), 오프라인 사용 가능

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

소스: github.com/astroway/astroway-mcp · npm: npmjs.com/package/@astroway/mcp · 호스팅: mcp.astroway.info/health

호스팅 (`mcp.astroway.info`) - 제로 설치

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

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

Cursor에 설치 →

Cursor는 딥링크에서 시크릿을 대체할 수 없습니다. ~/.cursor/mcp.json에는 리터럴 Bearer YOUR_API_KEY가 기록되며, 서버는 이에 대해 403 invalid_format으로 응답합니다.

버튼 클릭 후:

Cursor 설정 (⚙️ 우측 상단) → 도구 및 MCP → 목록에서 astroway-hosted를 찾으세요.
서버 옆의 점 세 개(⋯)를 클릭 → 구성 편집을 선택하세요.
Authorization 필드에서 Bearer YOUR_API_KEY를 대시보드에서 받은 실제 키인 Bearer aw_test_… (또는 aw_live_…)로 바꾸세요.
저장 → MCP 목록을 다시 열고 → 상태가 활성화됨 + 녹색 점 + 780+ tools enabled 카운터인지 확인하세요.

또는 파일을 직접 편집하세요: ~/.cursor/mcp.json (headers.Authorization).

설정 → 개발자 → 구성 편집을 열면 claude_desktop_config.json이 열립니다. 이 파일은 로컬 명령만 실행합니다. url만 있는 항목은 “일부 MCP 서버를 로드할 수 없습니다”라는 메시지와 함께 건너뛰어집니다. 호스팅된 서버는 mcp-remote 브리지를 통해 연결되며, Node.js가 필요합니다:

{
  "mcpServers": {
    "astroway-hosted": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.astroway.info/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer aw_live_..." }
    }
  }
}

Claude Desktop을 완전히 닫고(Cmd+Q) 다시 여세요. 키는 env에 있습니다. Windows용 Claude Desktop은 Bearer 뒤의 공백에서 인수를 분리하기 때문입니다.

설정 → 커넥터의 사용자 지정 커넥터 추가 대화 상자는 이름과 URL만 허용하며, Authorization 헤더 필드가 없으므로 현재 AstroWay 키를 통해 전달할 수 없습니다.

원격 url을 직접 허용하는 Cursor, Cline, Continue 및 Windsurf의 경우:

{
  "mcpServers": {
    "astroway-hosted": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": {
        "Authorization": "Bearer aw_live_..."
      }
    }
  }
}

구성 파일 경로:

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 → 다시 열기).

확인

curl https://mcp.astroway.info/health
# {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"…"}

클라이언트에서 다음을 요청하세요: “astroway-hosted에서 AstroWay 도구 이름 5개를 나열해 줘”. astroway_western_chart, astroway_horoscope_daily, astroway_vedic_panchang_full 등과 같은 이름이 반환되어야 합니다.

속도 제한

호스팅된 엔드포인트는 3단계 제한으로 보호됩니다: Cloudflare DDoS 계층 + 엣지 프록시 120 req/min/IP + 인메모리 버킷 60/60s/(IP+key). 실제 MCP 클라이언트(Claude Desktop, Cursor)는 이러한 제한에 근접하지 않습니다. 이들은 버스트 요청을 하지 않습니다. 자동화 / CI가 분당 120개 이상의 요청을 필요로 하는 경우, stdio 모드를 사용하세요 (이 모드에는 제한이 없으며, 요금제 속도 제한에 따라 api.astroway.info/v1/*를 통해 직접 통신합니다).

`mcp.astroway.info`가 일시적으로 사용 불가능한 경우

호스팅된 엔드포인트가 5xx를 반환하면 MCP 클라이언트는 tools/list에서 오류를 보게 됩니다. 이는 stdio 클라이언트에는 영향을 미치지 않습니다. stdio 클라이언트는 중간 호스팅 계층 없이 api.astroway.info/v1/*로 직접 이동하는 로컬 npm 패키지를 실행하기 때문입니다.

중요 통합을 위한 폴백: stdio 모드로 두 번째 MCP 서버를 구성에 추가하세요. 호스팅된 서버가 tools/list에 응답하지 않으면 클라이언트가 자동으로 이를 사용합니다:

{
  "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_..." }
    }
  }
}

호스팅된 엔드포인트의 실제 가동 시간은 status.astroway.info에서 확인할 수 있습니다. 5분 이상의 사고는 5영업일 이내에 사후 분석으로 게시됩니다 (/sla/ 참조).

Stdio (npm) - 로컬 개발용

@astroway/mcp는 서브프로세스로 로컬에서 실행되는 npm 패키지입니다. 단일 npm 패키지로 Claude Desktop, Cursor 및 모든 MCP 호환 클라이언트와 기본적으로 통합됩니다.

작동 방식

도구 목록은 라이브 OpenAPI 사양(api.astroway.info/v1/openapi.json)에서 빌드 시점에 생성됩니다. 각 패키지 릴리스는 모든 새 엔드포인트를 자동으로 가져오므로 수동으로 유지 관리할 필요가 없습니다.

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

tools/list는 설명과 입력 스키마(요청 본문 예시 포함)를 반환합니다.
tools/call은 ASTROWAY_API_KEY와 함께 https://api.astroway.info/v1/<path>로 HTTP POST 요청을 보냅니다.
응답은 구조화된 JSON으로 에이전트에게 반환됩니다.

각 릴리스는 SLSA provenance(Sigstore-attested)와 함께 제공됩니다. 이는 npm 패키지가 공개 저장소의 커밋에서 정확히 빌드되었음을 보장합니다.

설치

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/mcp.json에 다음을 추가하세요:

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

Cline / Continue / Windsurf / Copilot / VS Code MCP

동일한 npx @astroway/mcp 명령은 모든 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 클라이언트

stdio 서버로 실행하세요:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

개인 정보 보호 - v1.0.0+부터

이 MCP 서버는 당신이 실행하도록 지시하는 API 호출 외에는 어떤 것도 AstroWay로 다시 보내지 않습니다. 원격 측정, 분석, 옵트인/옵트아웃 스위치도 없으며, 기본적으로 조용합니다.

나가는 요청에는 AstroWay 백엔드가 자체 로그에서 MCP 트래픽과 직접 HTTP를 구별할 수 있도록 두 가지 식별 헤더가 포함됩니다:

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

이들 중 어느 것도 세션 ID, 머신 지문 또는 개인적인 정보를 포함하지 않습니다. 이는 표준 User-Agent 의미론이며, 모든 CLI 도구는 유사한 정보를 보냅니다.

하위 집합 등록 - v1.0.0+부터

카탈로그의 일부만 사용하는 경우, LLM의 컨텍스트 창을 작게 유지하기 위해 하위 집합을 등록하세요:

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // only these prefixes
    "ASTROWAY_READONLY": "1"                               // skip ai/horoscope/reports (LLM-backed, costs credits)
  }
}

일반적인 그룹: 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)을 건너뜁니다. 텍스트 생성에 크레딧을 소비하지 않고 순수한 결정론적 차트 계산을 원할 때 유용합니다.

안정성 약속 - v1.0.0+부터

카탈로그는 세션 동안 고정됩니다. 780개 이상의 도구, 12개의 프롬프트, 14개의 리소스가 빌드 시점에 게시된 npm 패키지에 포함되어 있으며, 연결 중에는 아무것도 변경되지 않습니다. 클라이언트가 첫 호출 후 tools/list를 캐시하는 경우, 전체 세션 동안 유효합니다.
도구 식별자는 주 버전 내에서 안정적입니다. astroway_<group>_<tool> 아래의 이름은 CHANGELOG.md에 사용 중단 알림 없이 v1.x 내에서 이름이 변경되거나 삭제되지 않으며, 단일 마이너 버전에서 병렬로 사용할 수 있습니다.
도구 입력 형태는 마이너 버전 내에서 안정적입니다. 제약 조건(정규식, 범위, 열거형)은 패치에서 제공되며, 필수 필드 추가는 마이너 버전 업그레이드를 필요로 합니다.
카탈로그 새로 고침: 재설치. npm i -g @astroway/mcp@latest (또는 구성의 npx -y @astroway/mcp 형식)는 다음 시작 시 현재 세트를 가져옵니다.

프롬프트 예시

연결 후 Claude에게 물어보세요:

출생 차트

내 출생 차트를 계산해 줘. 1990년 3월 15일 14:30, 키이우에서 태어났어. 태양, 달, 어센던트를 설명하고 밀접한 어스펙트를 찾아 줘.

Claude는 당신의 매개변수로 chart 도구를 호출하고, 구조화된 JSON을 받아 차트를 말로 설명할 것입니다.

트랜싯

2027년 동안 내 출생 차트에 어떤 중요한 느린 행성 트랜싯이 있을까?

Claude는 두 번의 도구 호출을 합니다: 먼저 transits (현재 스냅샷), 그 다음 transit-calendar (범위). 추세를 해석합니다.

베다 마하다샤

1985년 7월 22일 06:45 뭄바이에서 태어난 사람의 빔쇼타리 마하다샤를 실행해 줘. 이 사람은 지금 어떤 기간에 있어?

vedic/dashas/vimshottari/maha 도구를 통해 현재 기간의 정확한 UTC 타임스탬프를 얻을 수 있습니다.

시나스트리

두 차트를 비교해 줘: A - 1988년 6월 10일 09:15 런던, B - 1991년 11월 22일 22:40 베를린. 가장 강력한 교차 어스펙트는 무엇이야?

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

타로

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

재현성을 위해 고정된 시드를 사용하는 tarot/rider-waite/spread.

모든 도구 목록

연결 후 Claude에게 물어보세요:

모든 astroway 도구를 나열해 줘.

또는 명령줄에서:

ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (starts the stdio server; tool-list calls come from the MCP client over the protocol)

구성

변수	기본값	설명	버전부터
`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(접지 없음)은 *“7월 중 언젠가 토성이 당신의 목성과 삼각을 이룰 것입니다”*라고 말할 것입니다. 정확한 날짜 없이 ±15일의 오차가 있습니다. MCP 에이전트는 tool_use POST /v1/transits를 수행하고 실제 Swiss Ephemeris를 기반으로 초 단위까지 정확한 UTC 타임스탬프를 반환합니다.

장점은 LLM에 있는 것이 아니라 계산이 실제적이며 꾸며낸 것이 아니라는 보장에 있습니다.

패키지 배포

mcp.so 목록: mcp.so/server/astroway-mcp/astroway
mcpservers.org: 승인 대기 중 (2026년 5월 기준)
awesome-mcp-servers (punkpeye): PR #5972

링크

📦 npm: npmjs.com/package/@astroway/mcp
📘 API 문서: /docs/api/
🔑 가입: /dashboard/sign-up
💰 가격: /pricing/
🌐 공개 저장소 (MIT): github.com/astroway/astroway-mcp

도움이 되었나요?

수정 제안하기

마지막 업데이트: 2026. 10. 10.