NebulaBlock API Model Context Protocol (MCP) Interface

This repository contains the official server implementation for accessing the NebulaBlock API through the Model Context Protocol (MCP). By leveraging the optimized fastmcp library, this service translates all available NebulaBlock API capabilities into consumable tools, ensuring smooth and effective integration within any environment supporting the MCP standard.

Directory Organization

The project layout is organized as follows:

. ├── src/ │ ├── init.py │ ├── config.py │ ├── main.py │ ├── tools.py │ └── mcp_project.egg-info/ ├── tests/ │ ├── init.py │ └── test_main.py ├── scripts/ ├── docs/ ├── .env.example ├── .gitignore ├── pyproject.toml ├── README.md └── uv.lock

• src/: Core application logic, housing system configuration and tool definitions.
• tests/: Contains validation scripts, including unit and integration checks.
• scripts/: Designated area for auxiliary operational scripts (e.g., initial setup).
• docs/: Location for supplementary documentation materials.
• .env.example: A template file illustrating required environment variables.
• .gitignore: Specifies file patterns that Git should omit from version control.
• pyproject.toml: Defines project metadata, build parameters, dependency lists, and overall project specifications.
• README.md: This current descriptive file.
• uv.lock: The dependency resolution lock file generated by the uv package manager.

Setup and Deployment Procedures

Follow these sequential steps to establish the development environment:

1. Source Code Retrieval (if necessary): bash git clone https://github.com/Nebula-Block-Data/api-mcp cd mcp-project

2. Virtual Environment Creation: A segregated environment is strongly advised for dependency isolation. bash python3 -m venv .venv

3. Environment Activation:

   • Linux/macOS Users: bash source .venv/bin/activate

4. Dependency Installation: Dependencies are managed via pyproject.toml. Install setuptools and then install the package locally in editable mode. bash uv pip install -e .

   This action resolves and installs fastmcp along with all other specified prerequisites.

Initiating the NebulaBlock API MCP Server

The server is launched using the following command:

bash uv run -m src.main

Upon successful startup, the console should display a log similar to: [05/29/25 17:32:58] INFO Starting MCP server 'FastMCP' with transport 'stdio'

API Credential Configuration

The prerequisite NebulaBlock API access token can be supplied through two distinct mechanisms:

1. Via Command Line Flag: The key can be injected directly during application launch: bash python -m src.main --api-key your_nebula_block_api_key

   This method takes precedence over any setting found in configuration files.

2. Via Environment File: Create a file named .env in the root project folder and define the key there:

   NEBULA_BLOCK_API_KEY=your_nebula_block_api_key

   The application automatically loads credentials from this file if the --api-key argument is omitted.

Executing System Verification Routines

To confirm system integrity through testing, ensure your virtual environment is active and pytest is installed (it's included upon editable installation):

bash pytest

Successful execution will report the completion of all defined tests.

Connecting with an MCP Client Application

To leverage the functionality provided by this NebulaBlock API MCP gateway, the client application (e.g., an MCP plugin within an IDE) must be configured to establish a connection. The following JSON snippet illustrates a typical configuration for a client's settings.json:

{ "mcpServers": { "nebula": { "command": "~/path/to/uv", "args": [ "--directory", "~/path/to/nebulablock_mcp", "run", "-m", "src.main", "--api-key=YOUR_API_KEY" ] } } }

• Adjust ~/path/to/uv to point to the location of your installed uv binary.
• Set ~/path/to/nebulablock_mcp to the absolute location of this project directory.
• Substitute YOUR_API_KEY with your actual authorization credential.

Licensing Information

Distribution of this software is governed by the terms of the MIT License. Refer to the LICENSE file (if present) for complete particulars.