Bloomy MCP

Bloomy MCP

A Model Context Protocol (MCP) server for interacting with Bloom Growth's GraphQL API.

Overview

Bloomy MCP is a server that connects to Bloom Growth's GraphQL API and exposes it through the Model Context Protocol, enabling AI assistants to perform operations against the Bloom Growth platform.

Features

• Query Bloom Growth GraphQL API through MCP
• Retrieve query and mutation details
• Execute GraphQL queries and mutations via MCP tools
• Get authenticated user information
• Automatic schema introspection

Installation

Prerequisites

• Python 3.12 or higher
• Access to Bloom Growth API
• uv (recommended) or pip for package management

Package Management

This project recommends using uv, a fast Python package installer and resolver that serves as a drop-in replacement for pip/pip-tools. It's significantly faster than traditional package managers.

Installing uv

For other installation methods, see the uv documentation.

Setup

1. Clone this repository
2. Set up a Python virtual environment:
   python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate
3. Install the package in development mode:Using pip:
   pip install -e .
   Using uv (recommended):
   uv pip install -e .
   For development dependencies:
   uv pip install -e ".[dev]"

Environment Variables

Create a .env file with the following variables:

Usage

Cursor Integration

To use this MCP server with Cursor (AI-powered IDE):

1. Go to Cursor > Cursor Settings > MCP
2. Click on "Add new MCP server"
3. Configure the server with the following details:
   • Name: "Bloom Growth" (or "BG" or any name you prefer)
   • Type: Command
   • Command: uv run --project /path/to/your/repo/ --env-file /path/to/your/repo/.env bloomy-server

   Important: Replace /path/to/your/repo/ with the actual path to your bloomy-mcp repository (e.g., /Users/username/workspace/bloomy-mcp/).

Running the Server

Start the Bloomy MCP server:

Development Mode Inspection

For development and debugging purposes, you can use the MCP inspector tool:

This allows you to inspect the MCP server's behavior and responses during development.

Recommended Tools

For optimal development workflow:

• direnv: Use for managing environment variables and automatically loading them when entering the project directory
• uv: Use for fast and reliable package management

Setting up direnv:

1. Install direnv (e.g., brew install direnv on macOS)
2. Create a .envrc file in your project root:
   export BLOOM_API_URL=your_api_url export BLOOM_API_TOKEN=your_api_token
3. Run direnv allow to authorize the environment variables

This combination of tools (direnv + uv) provides an efficient environment for both secrets management and package management.

Available MCP Tools

The following MCP tools are available for AI assistants:

• get_query_details - Get detailed information about specific GraphQL queries
• get_mutation_details - Get detailed information about specific GraphQL mutations
• execute_query - Execute a GraphQL query or mutation with variables
• get_authenticated_user_id - Get the ID of the currently authenticated user

Available MCP Resources

• bloom://queries - Get a list of all available queries
• bloom://mutations - Get a list of all available mutations

Development

Project Structure

Dependencies

• mcp[cli] - Model Context Protocol server
• gql - GraphQL client library
• httpx - HTTP client
• pyyaml - YAML processing