MCP Analyst Toolkit

A Model Context Protocol (MCP) server that provides tools for data analysts and researchers. This server offers access to databases, change logs, and external APIs through the MCP interface.

Features

Database Integration

• ClickHouse Support: Execute queries against ClickHouse databases
• Database Discovery: List available databases and table schemas
• Query Templates: Pre-built query templates for common tasks

Data Resources

• Change Log Management: Access organizational change logs by time periods
• Historical Data: Track events and impacts across different quarters
• Structured Data Access: JSON-based change log data

Developer Tools

• GitHub Integration: Integration with GitHub repositories and APIs
• Extensible Architecture: Support for adding new tools and resources
• Type-Safe: Built with Python type hints

Installation

Prerequisites

• Python 3.11 or higher
• uv package manager (recommended)

Setup

1. Clone the repository:

   git clone <repository-url>
   cd mcp-analyst-toolkit
   

2. Install dependencies:

   uv pip install -e .
   

3. Run the MCP server:

   uv run mcp dev src/mcp_server/server.py
   

The server will start and display:

• MCP Inspector URL for interactive testing
• Session token for authentication
• Server status and configuration

Usage

Running the Server

Start the MCP server in development mode:

uv run mcp dev src/mcp_server/server.py

Access the MCP Inspector at http://localhost:6274/ to explore available tools and resources.

Integration with Claude Code

Example of config to start using these tools in Claude Code.

{
  "mcpServers": {
    "analyst_toolkit": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/repo/mcp-analyst-toolkit/src/mcp_server",
        "run",
        "server.py"
      ],
      "env": {
          "GITHUB_TOKEN": "your_github_token"
      }
    }
}

Available Tools

ClickHouse Database Tools

• execute_query: Execute SQL queries against ClickHouse databases
• get_databases: List all available databases
• get_table_schema: Get detailed schema information for specific tables

GitHub Tools

• Repository analysis and data extraction
• API integration for development workflows

Available Resources

Change Log Resources

• changelog://periods: List all available time periods
• changelog://<period>: Get detailed change logs for a specific period (e.g., changelog://2025_q1)

Example periods:

• 2025_q1: Q1 2025 organizational changes
• 2025_q2: Q2 2025 organizational changes

Project Structure

src/
├── mcp_server/
│   ├── __init__.py
│   ├── server.py              # Main MCP server implementation
│   ├── prompts/
│   │   ├── __init__.py
│   │   └── clickhouse_query.py # ClickHouse query templates
│   ├── resources/
│   │   ├── __init__.py
│   │   ├── change_log.py      # Change log resource handlers
│   │   └── change_log/        # Change log data files
│   │       ├── 2025_q1.json
│   │       ├── 2025_q2.json
│   │       └── ...
│   └── tools/
│       ├── __init__.py
│       ├── clickhouse.py      # ClickHouse database tools
│       └── github.py          # GitHub integration tools

Configuration

Change Log Data

Change log data is stored in JSON format under src/mcp_server/resources/change_log/. Each file represents a time period and contains structured event data:

[
  {
    "date": "2025-01-15",
    "event": "New Year Collection Launch",
    "impact": "Launched exclusive New Year fashion collection..."
  }
]

Development

Adding New Tools

1. Create a new tool module in src/mcp_server/tools/
2. Implement tool functions with proper type hints
3. Register the tool in src/mcp_server/server.py

Adding New Resources

1. Create resource handlers in `src/mcp_server/resou

... View full README on GitHub