Skip to main content
Glama
jungi0531

server-employee

by jungi0531
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Employment MCP Server

MCP 학습용으로 만든 고용 데이터 서버 World Bank API를 사용해서 농업/산업/서비스 섹터별 고용률을 조회한다.

MCP란?

Model Context Protocol의 약자. LLM에게 외부 도구와 데이터 접근 권한을 제공하는 표준 프로토콜이다.

공식 문서의 비유

MCP는 "AI 애플리케이션을 위한 USB-C 포트" 같은 것이다. USB-C가 전자기기를 연결하는 표준화된 방법을 제공하듯, MCP는 AI 애플리케이션을 외부 시스템에 연결하는 표준화된 방법을 제공한다.

또한 Language Server Protocol(LSP)에서 영감을 받았다. LSP가 IDE에서 프로그래밍 언어 지원을 표준화한 것처럼, MCP는 AI 애플리케이션에 컨텍스트와 도구를 통합하는 방식을 표준화한다.

핵심 구성 요소 (Primitives)

MCP 서버는 3가지 primitives를 제공한다:

  1. Resources (리소스)

    • 서버가 관리하는 데이터나 컨텐츠

    • 문서, 파일, API 응답 등

    • 예: World Bank API에서 가져온 고용 데이터

  2. Tools (도구)

    • LLM이 호출할 수 있는 함수

    • 작업을 수행하거나 외부 시스템과 상호작용

    • 예: get_employment_by_sector() 함수

  3. Prompts (프롬프트)

    • 재사용 가능한 프롬프트 템플릿

    • 워크플로우 자동화의 진입점

    • 서버가 제공하는 명령어 정의

이 프로젝트는 Tools 중심으로 구현되어 있다.

Related MCP server: World Bank Data360 MCP Server

프로젝트 구조

server-employee/
├── server.py            # FastMCP 인스턴스 생성
├── tools/api.py         # 도구(tool) 정의
├── main.py              # stdio 모드 실행 (로컬)
├── main_http.py         # HTTP 서버 실행 (원격)
└── pyproject.toml       # 의존성 관리

파일별 역할:

  • server.py: FastMCP 객체 하나 생성. 다른 파일에서 import해서 사용

  • tools/api.py: @mcp.tool() 데코레이터로 함수를 등록

  • main.py: stdio 통신으로 Claude Desktop과 직접 연결

  • main_http.py: HTTP 서버로 원격 접속 가능하게 함

핵심 개념

1. FastMCP 인스턴스 (server.py)

mcp = FastMCP("server-employee")

MCP 서버의 진입점. 모든 도구가 이 객체에 등록된다.

2. Tool 등록 (tools/api.py)

@mcp.tool()
async def get_employment_by_sector(country: str, year: int):
    # World Bank API 호출

@mcp.tool() 데코레이터로 일반 함수를 MCP 도구로 변환한다.

worldbank GDP 서버 참고: 잘 짜여진 코드를 보고 패턴을 학습했다.

1. 입력값 검증 (ISO 코드, 연도 범위)
2. API URL 구성
3. httpx로 비동기 요청
4. 에러 처리
5. 응답 포맷팅

3. 실행 모드

stdio (main.py)

  • 로컬 전용

  • Claude Desktop과 표준 입출력으로 통신

  • 가장 간단한 방식

HTTP (main_http.py)

  • 네트워크 접속 가능

  • Starlette + uvicorn 사용

  • 다른 컴퓨터에서 접속 가능

설치 및 실행

의존성 설치

uv sync

httpx, fastmcp, uvicorn 등이 설치된다.

로컬 실행

uv run python main.py

서버가 실행되지만 터미널에 아무것도 출력되지 않는다. stdio 모드로 대기 중이기 때문.

HTTP 서버 실행

uv run python main_http.py

http://0.0.0.0:8000에서 서버가 시작된다.

확인:

curl http://localhost:8000/ping
# {"ok": true, "status": "running"}

Claude Desktop 연결

로컬 연결

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

{
  "mcpServers": {
    "employment": {
      "command": "uv",
      "args": [
        "--directory",  
        "절대경로/server-employee",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}

경로는 본인 환경에 맞게 수정 필요. Claude Desktop 재시작 후 적용됨.

원격 연결

서버 실행 후:

{
  "mcpServers": {
    "employment-remote": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

다른 컴퓨터에서 접속: localhost를 서버 IP로 변경 예: http://192.168.0.10:8000/mcp

제공 도구

총 4개의 도구를 구현했다. 모두 World Bank API를 사용한다.

get_employment_by_sector

3개 섹터(농업/산업/서비스)의 고용률을 한 번에 조회한다.

get_employment_by_sector(country="US", year=2020)

파라미터:

  • country: ISO 2/3자 국가 코드 (US, KR, IN 등)

  • year: 연도 (1960~2100)

응답 예시:

{
  "country": "United States",
  "year": 2020,
  "employment": {
    "agriculture": {"percentage": 1.35},
    "industry": {"percentage": 19.62},
    "services": {"percentage": 79.03}
  }
}

get_agriculture_employment

농업 섹터만 조회한다.

get_agriculture_employment(country="IN", year=2020)
# 인도: 42.6% (농업 비중 높음)

get_industry_employment

산업(제조업 등) 섹터만 조회한다.

get_industry_employment(country="KR", year=2020)

get_services_employment

서비스업 섹터만 조회한다.

get_services_employment(country="US", year=2020)

World Bank Indicators

사용하는 지표:

  • SL.AGR.EMPL.ZS: Employment in agriculture (% of total)

  • SL.IND.EMPL.ZS: Employment in industry (% of total)

  • SL.SRV.EMPL.ZS: Employment in services (% of total)

World Bank에는 수천 개의 indicator가 있지만, 이 프로젝트에서는 위 3개만 사용한다.

원격 접속

로컬 네트워크

  1. HTTP 서버 실행: uv run python main_http.py

  2. IP 확인: ifconfig (Mac) / ipconfig (Windows)

  3. 접속: http://192.168.0.10:8000/mcp

인터넷 공개

ngrok 사용:

ngrok http 8000
# https://xxxx.ngrok.io/mcp

무료 버전은 세션마다 URL이 변경됨.

기타 방법:

  • 클라우드 배포 (AWS, GCP, Heroku 등)

  • 포트포워딩 (라우터 설정)

학습 노트

구조 설계

  1. server.py 분리: 여러 파일에서 같은 mcp 객체 공유. import로 재사용 가능.

  2. async/await 사용: API 호출 대기 시간에 다른 작업 가능. 동시 요청 처리에 유리.

  3. 헬퍼 함수: fetch_worldbank_indicator를 만들어 3개 함수에서 재사용. 코드 중복 제거.

배운 점

  • 입력값 검증의 중요성: ISO 코드 형식과 연도 범위를 체크해야 함

  • World Bank API 응답이 항상 데이터를 가지고 있지 않음. null 체크 필수

  • HTTP 서버에서 host="0.0.0.0" 사용해야 외부 접속 가능. 127.0.0.1은 로컬만

  • Claude Desktop은 원격 HTTP MCP를 지원하지 않음. Claude Web에서만 가능

주의사항

  • 보안: 현재 인증 없음. 실사용 시 API 키/토큰 필요

  • 방화벽: 8000 포트 개방 필요

  • 데이터: World Bank가 모든 국가/연도 데이터를 보유하지 않음

참고 자료

MCP 관련

API 관련

Available Tools

4 tools
get_agriculture_employmentA

특정 국가와 연도의 농업 섹터 고용 비율을 조회합니다.

Args: country: ISO 2- or 3-letter code (e.g., 'US', 'KR', 'IN') year: Four-digit year (>=1960)

Returns: 농업 섹터 고용 비율 (% of total employment)

ParametersJSON Schema
NameRequiredDescriptionDefault
yearYes
countryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the transparency burden. It discloses that the operation is a read-only query and specifies the return format (percentage of total employment). It also details input constraints (ISO 2/3-letter code, year >= 1960). However, it does not mention data availability, error behavior, or other operational nuances, but for a simple lookup this is largely adequate.

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?

The description is concise and well-structured: a one-sentence purpose statement followed by a clearly formatted Args section and a Returns line. Every sentence carries essential information, with no redundant or filler content.

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 simplicity (only two parameters, no nested objects) and the presence of an output schema, the description covers the core aspects: purpose, parameters, and return semantics. Minor omissions like error handling or data source details are not critical for a basic lookup, but the absence of any usage alternatives slightly reduces completeness.

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

Parameters5/5

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

Schema description coverage is 0%, so the description compensates fully. It documents each parameter beyond the schema's type information: country as ISO 2- or 3-letter code with examples, and year as a four-digit year with a minimum constraint. This adds real semantic value for the agent.

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's function: 'Queries the agricultural sector employment ratio for a specific country and year.' It uses a specific verb (조회합니다/retrieves), identifies the resource (agriculture sector employment rate), and distinguishes itself from sibling tools (get_industry_employment, get_services_employment) by explicitly focusing on agriculture.

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

Usage Guidelines3/5

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

The description implies the use case—querying agriculture employment for a country/year—but provides no explicit guidance on when to choose this tool over siblings or when not to use it. There are no exclusion criteria or alternative tool references, so the context is only implicit.

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

get_employment_by_sectorA

특정 국가와 연도의 섹터별 고용 데이터를 조회합니다. Services, Agriculture, Industry 세 섹터의 고용 비율(%)을 반환합니다.

Args: country: ISO 2- or 3-letter code (e.g., 'US', 'KR', 'IN') year: Four-digit year (>=1960)

Returns: 섹터별 고용 비율 정보. 데이터가 없으면 메시지 반환.

ParametersJSON Schema
NameRequiredDescriptionDefault
yearYes
countryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations, the description carries the full burden. It discloses that the return format is employment ratio percentages for three sectors and that a message is returned if no data exists. This adds meaningful behavioral context beyond what the schema provides, though it does not mention permissions or error specifics, which are less critical for a read-only query tool.

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?

The description is concise, structured with clearly labeled Args and Returns sections, and contains no wasted words. Every sentence adds useful information, and the use of bullet-style formatting enhances readability.

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?

For a simple two-parameter read tool with no annotations, the description is complete: it covers purpose, parameter constraints, return format, and the missing-data case. The sibling tool names and context signals fill in the remaining guidance, making the description sufficient for correct invocation.

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

Parameters5/5

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

Schema description coverage is 0%, so the description compensates fully. It defines country as an ISO 2- or 3-letter code with examples, and year as a four-digit number >=1960. These constraints are not present in the schema, making the parameter documentation highly valuable.

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 it retrieves employment data by sector for a specific country and year, and explicitly lists the three sectors (Services, Agriculture, Industry). This distinguishes it from sibling tools that focus on a single sector, fulfilling the 'specific verb+resource' test.

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 that this tool returns all three sectors at once, contrasting with the sibling tools that likely return data for a single sector. However, it does not explicitly say 'use this when you need all sectors' or name the alternatives, so the guidance is clear but not fully explicit.

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

get_industry_employmentA

특정 국가와 연도의 산업 섹터 고용 비율을 조회합니다.

Args: country: ISO 2- or 3-letter code (e.g., 'US', 'KR', 'IN') year: Four-digit year (>=1960)

Returns: 산업 섹터 고용 비율 (% of total employment)

ParametersJSON Schema
NameRequiredDescriptionDefault
yearYes
countryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

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

With no annotations provided, the description carries the burden. It discloses the year constraint (>=1960) and the return format (percentage of total employment), but it does not mention permissions, rate limits, or error behavior. For a simple read query this is moderate, but gaps remain.

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?

The description is very compact, with three clear sections: summary, arguments, returns. Every sentence provides needed information with no redundancy or fluff.

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?

The description is complete for a simple two-parameter lookup: it covers input format, output semantics, and a constraint on year. With an output schema existing, it need not explain returns further. Minor gaps include lack of mention of data availability limitations or edge cases, but overall it is sufficient.

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

Parameters5/5

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

Schema coverage is 0% (parameters only have titles). The description compensates strongly by providing ISO code format and examples for country, and explicitly stating year must be a four-digit year >=1960. This goes well beyond the schema's minimal information.

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 explicitly states '특정 국가와 연도의 산업 섹터 고용 비율을 조회합니다' (queries industry sector employment ratio for a specific country and year), which is a specific verb+resource+scope. It clearly distinguishes from sibling tools like agriculture or services employment.

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

Usage Guidelines3/5

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

The description implies usage by its specificity to industry sector and the required country/year parameters, but it does not explicitly mention when to use this tool versus sibling alternatives or any exclusions. Since sibling tools exist and are not referenced, guidance is only implied.

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

get_services_employmentA

특정 국가와 연도의 서비스 섹터 고용 비율을 조회합니다.

Args: country: ISO 2- or 3-letter code (e.g., 'US', 'KR', 'IN') year: Four-digit year (>=1960)

Returns: 서비스 섹터 고용 비율 (% of total employment)

ParametersJSON Schema
NameRequiredDescriptionDefault
yearYes
countryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses the year constraint (>=1960) and country code format (ISO 2- or 3-letter), and clarifies the output as a percentage of total employment. This provides meaningful behavioral context beyond the schema.

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?

The description is compact and well-structured: a purpose sentence followed by Args and Returns sections. Every sentence adds value, with no redundancy or filler.

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?

For a simple query tool with 2 parameters and an existing output schema, the description provides all necessary input constraints and output details. The only gap is the lack of usage comparisons with sibling tools, which is minor given the clear sector-specific purpose.

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

Parameters5/5

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

Schema description coverage is 0%, so the description fully compensates by defining the country code format with examples and the year range. It adds critical meaning that the bare schema types ('string', 'integer') lack.

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 uses the specific verb '조회합니다' (queries) and clearly identifies the resource: service sector employment ratio for a given country and year. The sector-specific focus distinguishes it from sibling tools like get_agriculture_employment and get_industry_employment.

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

Usage Guidelines3/5

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

The description does not explicitly state when to use this tool over alternatives or mention exclusions. The naming implies it is for services sector data, but no direct comparison to siblings is provided.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation4/5

The three sector-specific tools are clearly distinct (agriculture, industry, services), but get_employment_by_sector overlaps by returning all three sectors at once. This creates minor ambiguity about which tool to call when only one sector is needed, though the descriptions clearly indicate the granularity difference.

Naming Consistency5/5

All tools follow a consistent get_<something>_employment pattern with snake_case. The combined tool uses get_employment_by_sector, while the others are get_agriculture_employment, get_industry_employment, get_services_employment, all following a predictable verb_noun structure.

Tool Count5/5

Four tools is well-scoped for a server providing sectoral employment data. Each tool serves a clear role: one combined query and three specific sector queries. The count feels appropriate, not excessive or thin.

Completeness5/5

The server covers the full domain of sectoral employment ratios: agriculture, industry, and services, plus a combined view. There are no obvious missing operations for a read-only data source; it provides all sector breakdowns available.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • World Bank MCP Server

    anshumax
    F
    license
    B
    quality
    F
    maintenance
    Enables AI assistants to interact with the World Bank open data API, allowing for listing and analysis of indicators across available countries.
    1
    50

  • World Bank Data360 MCP Server

    llnOrmll
    A
    license
    A
    quality
    D
    maintenance
    Enables access to World Bank Data360 API with 1000+ economic and social indicators across 200+ countries and 60+ years of historical data, allowing searches, temporal coverage checks, and filtered data retrieval through natural language queries.
    5
    1
    MIT

  • WorldBank GDP & Employment MCP

    Moderator11
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that interfaces with the WorldBank API to retrieve economic and labor market data such as GDP and employment indicators. It allows LLMs to query global development statistics including unemployment rates, labor force participation, and sectoral employment data.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jungi0531/mcp-server-employee'

If you have feedback or need assistance with the MCP directory API, please join our Discord server