A Model Context Protocol server that connects AI assistants to Bloom Growth's GraphQL API, enabling them to query data and execute operations against the Bloom Growth platform.
A Model Context Protocol (MCP) server for interacting with Bloom Growth's GraphQL API.
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.
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.
curl -sSf https://astral.sh/uv/install.sh | shFor other installation methods, see the uv documentation.
python -m venv .venv
source .venv/bin/activate # On Windows: .venvScriptsactivateUsing pip:
pip install -e .Using uv (recommended):
uv pip install -e .For development dependencies:
uv pip install -e ".[dev]"Create a .env file with the following variables:
BLOOM_API_URL=<Your Bloom API URL>
BLOOM_API_TOKEN=<Your Bloom API Token>To use this MCP server with Cursor (AI-powered IDE):
Configure the server with the following details:
Name: "Bloom Growth" (or "BG" or any name you prefer)
uv run --project /path/to/your/repo/ --env-file /path/to/your/repo/.env bloomy-serverImportant: Replace /path/to/your/repo/ with the actual path to your bloomy-mcp repository (e.g., /Users/username/workspace/bloomy-mcp/).
Start the Bloomy MCP server:
bloomy-serverFor development and debugging purposes, you can use the MCP inspector tool:
npx @modelcontextprotocol/inspector bloomy-serverThis allows you to inspect the MCP server's behavior and responses during development.
For optimal development workflow:
Setting up direnv:
brew install direnv on macOS).envrc file in your project root:
export BLOOM_API_URL=your_api_url
export BLOOM_API_TOKEN=your_api_tokendirenv allow to authorize the environment variablesThis combination of tools (direnv + uv) provides an efficient environment for both secrets management and package management.
The following MCP tools are available for AI assistants:
get_query_details - Get detailed information about specific GraphQL queriesget_mutation_details - Get detailed information about specific GraphQL mutationsexecute_query - Execute a GraphQL query or mutation with variablesget_authenticated_user_id - Get the ID of the currently authenticated userbloom://queries - Get a list of all available queriesbloom://mutations - Get a list of all available mutationssrc/
└── 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 implementationmcp[cli] - Model Context Protocol servergql - GraphQL client libraryhttpx - HTTP clientpyyaml - YAML processing[
{
"description": "Get detailed information about specific GraphQL queries. Retrieves argument requirements, return type information, descriptions, and example usage for the specified queries. Args: query_names: Comma-separated list of query names to get details for Returns: A YAML-formatted string containing detailed information about the requested queries ",
"inputSchema": {
"properties": {
"query_names": {
"title": "Query Names",
"type": "string"
}
},
"required": [
"query_names"
],
"title": "get_query_detailsArguments",
"type": "object"
},
"name": "get_query_details"
},
{
"description": "Get detailed information about specific GraphQL mutations. Retrieves argument requirements, return type information, descriptions, and example usage for the specified mutations. Args: mutation_names: Comma-separated list of mutation names to get details for Returns: A YAML-formatted string containing detailed information about the requested mutations ",
"inputSchema": {
"properties": {
"mutation_names": {
"title": "Mutation Names",
"type": "string"
}
},
"required": [
"mutation_names"
],
"title": "get_mutation_detailsArguments",
"type": "object"
},
"name": "get_mutation_details"
},
{
"description": "Execute a GraphQL query or mutation with variables. Parses and executes the provided GraphQL operation string with optional variables. Args: query: Raw GraphQL query or mutation string variables: Optional dictionary of variables to use in the operation Returns: Dictionary containing the operation results or an error message string Raises: Exception: Handled internally, returns error message as string ",
"inputSchema": {
"properties": {
"query": {
"title": "Query",
"type": "string"
},
"variables": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
],
"title": "Variables"
}
},
"required": [
"query"
],
"title": "execute_queryArguments",
"type": "object"
},
"name": "execute_query"
},
{
"description": "Get the ID of the currently authenticated user. Uses a special mutation to retrieve the ID of the user associated with the current API token. Returns: User ID string if successful, None if user not found, or error message string Raises: Exception: Handled internally, returns error message as string ",
"inputSchema": {
"properties": {},
"title": "get_authenticated_user_idArguments",
"type": "object"
},
"name": "get_authenticated_user_id"
}
]