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=
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:

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