Skip to main content
Glama
haebojagu

mcp-budget-server

by haebojagu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mcp-budget-server

광고 AE 견적서 정산용 MCP 서버 (stdio). 견적서 데이터를 받아 청구액 · 외주비 · 내수 · 내수율을 계산합니다.

금액 표기를 똑똑하게 정규화합니다 — "1.5억", "3,000만", "₩95,120,000", "△100,000"(회계식 음수), "(100,000)"(괄호 음수) 모두 정수(원)로 인식합니다.

파서 로직은 sns-dashboard의 parse-amount.ts를 독립 복사해 사용합니다.

요구 사항

  • Node.js 18 이상

  • (사용처) Claude Desktop 또는 MCP를 지원하는 클라이언트

  • (선택) analyze_youtube_comments의 유튜브 URL 자동 수집 기능을 쓰려면 YouTube Data API v3 키

Related MCP server: Amazon Ads Manager MCP Server

설치

git clone https://github.com/<YOUR_ID>/mcp-budget-server
cd mcp-budget-server
npm install
npm run build      # tsc → dist/index.js 생성

dist/는 git에 포함되지 않으므로 **클론 후 반드시 npm run build**를 실행해야 합니다.

YouTube API 키 발급 및 설정 (선택)

analyze_youtube_comments 도구에서 댓글을 직접 붙여넣지 않고 유튜브 URL로 자동 수집하려면 API 키가 필요합니다. 키가 없어도 댓글을 수동으로 붙여넣는 기존 방식은 그대로 동작합니다.

1) 키 발급

  1. Google Cloud Console에서 프로젝트를 생성(또는 선택)합니다.

  2. APIs & Services → Library에서 YouTube Data API v3를 검색해 **사용 설정(Enable)**합니다.

  3. APIs & Services → Credentials → Create Credentials → API key로 키를 발급받습니다.

  4. (권장) 발급된 키를 YouTube Data API v3로 제한해 오남용을 방지합니다.

2) 키 설정 — 둘 중 하나

방법 A: .env 파일 (로컬에서 node dist/index.js로 직접 실행할 때)

cp .env.example .env
# .env 파일을 열어 아래처럼 키 입력
# YOUTUBE_API_KEY=발급받은_키

방법 B: Claude Desktop 설정의 env 필드 (Claude Desktop에 등록해 쓸 때 더 확실한 방법)

{
  "mcpServers": {
    "budget": {
      "command": "node",
      "args": ["/Users/<YOU>/mcp-budget-server/dist/index.js"],
      "env": {
        "YOUTUBE_API_KEY": "발급받은_키"
      }
    }
  }
}

.env는 .gitignore에 포함되어 있어 git에 커밋되지 않습니다. 절대 키를 코드에 하드코딩하거나 커밋하지 마세요.

키가 없는 상태에서 youtube_urls를 입력하면, 도구가 에러 대신 ".env에 키를 추가하거나 댓글을 직접 붙여넣어주세요" 안내 메시지를 반환합니다.

Claude Desktop에 등록

1) 설정 파일 위치

OS

경로

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

설정 파일을 여는 명령:

# macOS
open "~/Library/Application Support/Claude/claude_desktop_config.json"
# Windows (PowerShell)
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

2) mcpServers에 budget 서버 추가

args에는 빌드된 dist/index.js의 절대 경로를 넣습니다.

macOS 예시

{
  "mcpServers": {
    "budget": {
      "command": "node",
      "args": ["/Users/<YOU>/mcp-budget-server/dist/index.js"]
    }
  }
}

Windows 예시 (경로는 \\ 또는 / 모두 가능)

{
  "mcpServers": {
    "budget": {
      "command": "node",
      "args": ["C:\\Users\\<YOU>\\mcp-budget-server\\dist\\index.js"]
    }
  }
}

이미 mcpServers나 preferences 등 다른 키가 있다면 budget 항목만 추가하세요(기존 설정 유지).

3) Claude Desktop 재시작

설정 저장 후 Claude Desktop을 완전히 종료(⌘Q / 트레이 종료) 후 재시작해야 서버가 로드됩니다. 입력창의 🔌(도구) 아이콘에서 budget이 보이면 성공입니다.

사용법

A. 엑셀 견적서 파일로 사용 (권장 흐름)

  1. Claude Desktop 대화창에 견적서 엑셀(.xlsx) 파일을 첨부합니다.

  2. 다음처럼 요청합니다:

    "이 견적서에서 청구액과 외주비를 뽑아서 analyze_estimate로 내수율 계산해줘."

  3. Claude가 엑셀 내용을 읽어 청구/외주 금액을 추출한 뒤 analyze_estimate 도구를 호출하고, 청구액·외주비·내수·내수율 결과를 보여줍니다.

엑셀 파싱 자체는 Claude(모델)가 첨부 파일을 읽어 수행하고, 이 서버는 추출된 금액의 정규화·합산·내수율 계산을 담당합니다. "1.5억" 같은 표기가 섞여 있어도 정확히 계산됩니다.

B. 도구를 직접 호출 (금액을 직접 입력)

// analyze_estimate 입력
{
  "billing": ["1.5억"],
  "outsource": ["3,000만", "₩20,000,000", { "label": "편집", "amount": "1,000만" }, "△5,000,000"]
}

결과: 청구액 ₩150,000,000 · 외주비 ₩55,000,000 · 내수 ₩95,000,000 · 내수율 63.3%

도구 레퍼런스: analyze_estimate

입력

필드

타입

설명

billing

(string | number | {label?, amount})[]

청구액(클라이언트 청구) 항목들

outsource

(string | number | {label?, amount})[]

외주비(협력사 지급) 항목들

금액은 문자열 표기 가능: "1.5억", "3,000만", "₩20,000,000", "△5,000,000"(음수).

출력 (structuredContent)

필드

설명

billingTotal

청구액 합계 (원)

outsourceTotal

외주비 합계 (원)

naesu

내수 = 청구액 − 외주비 (원)

naesuRate

내수율(%) = 내수 / 청구액 × 100

billingItems / outsourceItems

정규화된 항목 {label, amount} 목록

도구 레퍼런스: analyze_youtube_comments

유튜브 댓글을 정성 분석(감성 분포·대표 반응·키워드·인사이트)하기 위한 프롬프트 스캐폴딩 도구. 계산이 아니라 Claude가 분석을 작성하도록 구조화된 지침을 반환합니다.

입력

필드

타입

설명

comments

string (선택)

수동으로 붙여넣은 댓글 텍스트 (여러 줄)

youtube_urls

string (선택)

자동 수집할 유튜브 영상 URL들, 줄바꿈으로 구분. YOUTUBE_API_KEY 필요

video_context

string (선택)

영상/캠페인 설명

comments와 youtube_urls 중 최소 하나는 입력해야 합니다. 둘 다 입력하면 두 출처의 댓글을 합쳐서 분석합니다.

출력 (structuredContent)

필드

설명

comments

수동 입력 + 자동 수집을 합친 최종 댓글 텍스트

sources

youtube_urls로 자동 수집에 성공한 영상 목록 (url, videoId, commentCount)

warnings

URL 인식 실패, API 키 미설정, 수집 실패 등 경고 메시지

structure

작성할 5개 섹션 (감성 분포 / 대표 긍정 반응 / 대표 부정·이슈 반응 / 핵심 키워드 / 종합 인사이트)

instructions

Claude가 따라야 할 작성 규칙

YouTube Data API 호출은 youtube_urls가 주어지고 YOUTUBE_API_KEY가 설정된 경우에만 발생하며, 영상당 최대 100개 댓글(commentThreads.list)을 가져옵니다.

동작 확인 (스모크 테스트)

npm run build && node smoke-test.mjs           # analyze_estimate
node smoke-test-report.mjs                     # generate_campaign_report
node smoke-test-youtube.mjs                    # analyze_youtube_comments (키 없음/있음 케이스 포함)

stdio로 initialize → tools/list → tools/call을 수행해 각 도구의 동작을 검증합니다. smoke-test-youtube.mjs는 YOUTUBE_API_KEY가 없는 환경과 있는 환경을 각각 시뮬레이션해 안내 메시지·경고 처리를 확인합니다.

기술 스택

  • @modelcontextprotocol/sdk (stdio transport)

  • zod (입력/출력 스키마)

  • dotenv (.env에서 YOUTUBE_API_KEY 로드)

  • TypeScript (ESM, NodeNext)

Available Tools

2 tools
analyze_estimate견적서 정산 분석A

광고 견적서/청구서 데이터를 입력받아 청구액 합계·외주비 합계·내수(청구−외주)·내수율(%)을 계산합니다. 금액은 "1.5억", "1,000만", "₩95,120,000", "△100,000"(음수) 같은 표기를 모두 인식합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
billingNo청구액(클라이언트 청구) 항목들. 보통 1건이지만 여러 건 합산 가능.
outsourceNo외주비(협력사 지급) 항목들. 여러 건 합산.

Output Schema

ParametersJSON Schema
NameRequiredDescription
naesuYes내수 = 청구액 − 외주비 (원)
currencyYes
naesuRateYes내수율(%) = 내수 / 청구액 × 100, 소수 1자리
billingItemsYes
billingTotalYes청구액 합계 (원)
outsourceItemsYes
outsourceTotalYes외주비 합계 (원)

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. It explains input recognition and output calculations but does not mention side effects (e.g., read-only), authorization needs, or rate limits. For a computation tool, these are less critical, but transparency could be improved by stating it is a pure function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff. The first sentence front-loads the core calculations, the second adds input format capabilities. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, 100% schema coverage, and presence of an output schema (though not shown), the description is complete. It explains all key aspects: inputs, calculations, and input format handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. The description adds value by explaining the business meaning of 'billing' (client charges) and 'outsource' (vendor payments) and by describing the output metrics. This goes beyond the schema's structural description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('calculates') and the resource (estimate/invoice data) and lists specific metrics (total billing, outsourcing, domestic, domestic rate). It implicitly distinguishes from the sibling tool 'generate_campaign_report' which likely generates a report rather than performing calculations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for analyzing ad estimate/invoice data, but does not explicitly state when not to use or provide alternatives. The sibling tool context helps differentiate, but explicit guidance on when to choose this over generate_campaign_report would improve clarity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_campaign_report캠페인 리포트 초안 생성 가이드A

미디어 성과 + 소비자 반응 + 캠페인 컨텍스트를 입력받아, 광고주 보고용 캠페인 리포트를 작성하기 위한 구조화된 지침(5개 섹션)과 정리된 데이터를 반환합니다. 계산 도구가 아니라, Claude가 이 구조대로 리포트를 작성하도록 안내하는 프롬프트 스캐폴딩입니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
media_dataYes미디어팀 리포트 내용 — 숫자/표/텍스트 무엇이든 (노출·조회·VTR·CPV·채널별 성과 등)
consumer_dataYes소비자 반응 — 댓글, 긍/부정, 키워드 언급량 등
campaign_contextYes브랜드명, 캠페인 목적, 목표 KPI 등 배경 정보

Output Schema

ParametersJSON Schema
NameRequiredDescription
structureYes작성해야 할 리포트 섹션 5개 (순서·제목·지침)
media_dataYes
instructionsYesClaude가 따라야 할 종합 작성 규칙
consumer_dataYes
campaign_contextYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the tool returns structured guidelines and data, not a final report, and that it serves as prompt scaffolding for Claude. It does not mention side effects or permissions, but the nature of the tool (non-destructive, non-calculating) is adequately conveyed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no waste. The first sentence states inputs and outputs precisely; the second sentence clarifies its role as non-calculative scaffolding. Information is front-loaded and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 string parameters, output schema present), the description covers the core functionality, inputs, outputs, and distinguishes from the sibling. It could elaborate on the 5 sections mentioned, but the output schema likely fills that gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by specifying types of data expected for each parameter (e.g., media_data includes impressions, views, VTR, CPV). This provides context beyond the schema's minimal descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool takes media performance, consumer response, and campaign context as inputs, and returns structured guidelines (5 sections) and organized data for a campaign report. It explicitly distinguishes itself from a calculation tool, aligning with the sibling tool 'analyze_estimate'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clarifies that this is not a calculation tool, implying use for report scaffolding rather than numeric analysis. However, it could more explicitly state when to use this tool versus the sibling, though the distinction is clear from the context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observedanalyze_estimate
    • First observedgenerate_campaign_report
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one calculates budget metrics from invoices, the other provides a structured guide for campaign report generation. There is no overlap.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern (analyze_estimate, generate_campaign_report) using snake_case, which is predictable and clear.

Tool Count3/5

With only two tools, the server feels thin for a budget server. While the tools are well-defined, a typical budget domain would benefit from additional tools (e.g., list budgets, update budget).

Completeness2/5

The tool surface is incomplete for a budget server. It lacks fundamental operations like managing budgets or retrieving raw data. The generate_campaign_report tool is a scaffold rather than a functional tool, leaving significant gaps.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers