Skip to main content
Glama

BLS MCP Server

by kovashikawa
GitHub
Python
MIT License
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

BLS MCP Server

A standalone MCP (Model Context Protocol) server for Bureau of Labor Statistics (BLS) data, designed to work with multiple LLM clients through both local and remote connections.

Features

  • Official MCP SDK: Built with the official mcp Python SDK for full protocol control

  • Mock Data First: Uses realistic mock BLS data for rapid development and testing

  • Multiple Transports: Supports both stdio (local) and SSE (remote via ngrok)

  • Multi-LLM Compatible: Test with Claude, GPT-4, and other MCP-compatible clients

  • Modular Design: Clean separation between tools, resources, and data providers

Quick Start

Installation

Option 1: Using UV (Recommended - 10x faster!)

# Install uv (if not already installed) curl -LsSf https://astral.sh/uv/install.sh | sh # Navigate to project cd bls_mcp # Sync dependencies (creates .venv automatically) uv sync # Run the server ./scripts/uv_start_server.sh # Test the server ./scripts/uv_test_client.sh

See UV_USAGE.md for comprehensive UV documentation.

Option 2: Using pip (Traditional)

# Clone the repository cd bls_mcp # Create virtual environment python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -e . # Or install with dev dependencies pip install -e ".[dev]"

Running the Server (Local)

# With UV (recommended) ./scripts/uv_start_server.sh # Or with traditional Python python scripts/start_server.py

Testing with MCP Inspector

# Install MCP inspector (if not already installed) npm install -g @modelcontextprotocol/inspector # Run inspector mcp-inspector python scripts/start_server.py

Project Status

Current Phase: Phase 1 - Foundation

  • Project structure created

  • Configuration files set up

  • Mock data system implemented

  • Core MCP server implemented

  • Basic tools implemented

  • Tests written

Available Tools (Phase 1)

get_series

Fetch BLS data series by ID with optional date range filtering.

Parameters:

  • series_id (string, required): BLS series ID (e.g., "CUUR0000SA0")

  • start_year (integer, optional): Start year for data range

  • end_year (integer, optional): End year for data range

Example:

{ "name": "get_series", "arguments": { "series_id": "CUUR0000SA0", "start_year": 2020, "end_year": 2024 } }

list_series

List available BLS series with optional filtering.

Parameters:

  • category (string, optional): Filter by category (e.g., "CPI", "Employment")

  • limit (integer, optional): Maximum number of results (default: 50)

get_series_info

Get detailed metadata about a specific BLS series.

Parameters:

  • series_id (string, required): BLS series ID

Architecture

Directory Structure

bls_mcp/ ├── src/bls_mcp/ │ ├── server.py # Main MCP server │ ├── transports/ │ │ ├── stdio.py # stdio transport (local) │ │ └── sse.py # SSE transport (remote - Phase 2) │ ├── tools/ │ │ ├── base.py # Base tool class │ │ ├── get_series.py # Get series tool │ │ ├── list_series.py # List series tool │ │ └── get_series_info.py # Get series info tool │ ├── data/ │ │ ├── mock_data.py # Mock data provider │ │ └── fixtures/ # JSON data fixtures │ └── utils/ │ ├── logger.py # Logging configuration │ └── validators.py # Input validation ├── tests/ # Test suite ├── scripts/ # Utility scripts └── docs/ # Documentation

Data Flow

  1. Client Request → MCP protocol (JSON-RPC)

  2. Transport Layer → stdio or SSE

  3. Server Router → Route to appropriate tool

  4. Tool Execution → Fetch data from provider

  5. Data Provider → Mock or real data source

  6. Response → JSON formatted response

Mock Data

The server uses realistic mock BLS data that follows the actual BLS API structure:

  • CPI Series: Consumer Price Index data for various categories

  • Time Range: 2020-2024 with monthly data points

  • Coverage: Multiple categories (All Items, Food, Energy, Housing, etc.)

  • Realistic Values: Based on actual BLS data patterns

Development

Running Tests

# Run all tests pytest # Run with coverage pytest --cov=bls_mcp # Run specific test file pytest tests/test_tools.py

Code Quality

# Format code black src/ tests/ # Lint code ruff check src/ tests/ # Type checking mypy src/

Adding New Tools

  1. Create tool file in src/bls_mcp/tools/

  2. Implement tool class following the base pattern

  3. Register tool in server.py

  4. Add tests in tests/test_tools.py

  5. Update documentation

Roadmap

Phase 1: Foundation (Current)

  • Project setup and configuration

  • Mock data system

  • Core MCP server with stdio transport

  • Basic tools (get_series, list_series, get_series_info)

  • Unit tests

Phase 2: Remote Access

  • SSE transport implementation

  • ngrok integration

  • Multi-LLM client testing

  • Enhanced tools with visualization

Phase 3: Advanced Features

  • MCP resources (catalogs, documentation)

  • Pre-built prompts for analysis

  • Advanced analysis tools

  • Migration path to real BLS data

Configuration

Create a .env file (copy from .env.example):

MCP_SERVER_PORT=3000 MCP_SERVER_HOST=localhost LOG_LEVEL=INFO DATA_PROVIDER=mock

Contributing

This is a personal project, but suggestions and feedback are welcome!

License

MIT License - see LICENSE file for details

Related Projects

Support

For issues or questions, please refer to the documentation in the docs/ directory or check the PLAN.md file for development details.

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Enables access to Bureau of Labor Statistics (BLS) economic data including Consumer Price Index, employment statistics, and other labor market indicators. Supports fetching data series, listing available datasets, and retrieving metadata through natural language queries.

  1. Features
    1. Quick Start
      1. Installation
      2. Running the Server (Local)
      3. Testing with MCP Inspector
    2. Project Status
      1. Available Tools (Phase 1)
        1. get_series
        2. list_series
        3. get_series_info
      2. Architecture
        1. Directory Structure
        2. Data Flow
      3. Mock Data
        1. Development
          1. Running Tests
          2. Code Quality
          3. Adding New Tools
        2. Roadmap
          1. Phase 1: Foundation (Current)
          2. Phase 2: Remote Access
          3. Phase 3: Advanced Features
        3. Configuration
          1. Contributing
            1. License
              1. Related Projects
                1. Support

                  New MCP Servers

                  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/kovashikawa/bls_mcp'

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