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

curl -sSf https://astral.sh/uv/install.sh | sh

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:

BLOOM_API_URL=<Your Bloom API URL>
BLOOM_API_TOKEN=<Your Bloom API Token>

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:

bloomy-server

Development Mode Inspection

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

npx @modelcontextprotocol/inspector bloomy-server

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

src/
  └── bloomy_mcp/
      ├── __init__.py        # Package initialization
      ├── client.py          # GraphQL client implementation
      ├── formatters.py      # Data formatting utilities
      ├── introspection.py   # GraphQL schema introspection
      ├── operations.py      # GraphQL operation utilities
      └── server.py          # MCP server implementation

Dependencies

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