# Infor Birst MCP Server
An MCP (Model Context Protocol) server that exposes Infor Birst's analytics platform capabilities as AI-consumable tools.
## Features
**20 MCP Tools** enabled by default, organized in 5 tiers (up to 25 with optional features):
### Tier 1: Core Query Tools (0-5 tools, optional)
These tools require additional Birst entitlements and are **disabled by default**:
**GenAI Tools** (require Birst AI entitlement - set `BIRST_ENABLE_GENAI=true`):
- `birst_generate_bql` - Convert natural language to BQL queries
- `birst_search_data` - Search data warehouse with natural language
- `birst_generate_chart` - Generate chart specifications from text
**ICW Tools** (require application provisioning - set `BIRST_ENABLE_ICW=true`):
- `birst_execute_query` - Execute BQL queries and return results
- `birst_validate_query` - Validate BQL syntax before execution
### Tier 2: Discovery Tools (6 tools)
- `birst_list_spaces` - List all accessible analytical spaces
- `birst_get_space` - Get detailed space information
- `birst_list_reports` - List reports in a space (with pagination)
- `birst_list_dashboards` - List dashboards in collections
- `birst_list_collections` - List collections in a space
- `birst_search_catalog` - Search catalog entities
### Tier 3: Infrastructure Tools (5 tools)
- `birst_list_connections` - List data connections
- `birst_list_sources` - List data sources
- `birst_list_variables` - List space variables
- `birst_list_hierarchies` - List dimensional hierarchies
- `birst_get_dataflow` - Get data flow visualization
### Tier 4: Workflow Tools (4 tools)
- `birst_list_workflows` - List available workflows
- `birst_run_workflow` - Trigger workflow execution
- `birst_get_workflow_status` - Monitor workflow status
- `birst_list_workflow_runs` - Get workflow execution history
### Tier 5: Administration Tools (4 tools)
- `birst_list_users` - List users in account
- `birst_list_space_users` - List users with space access
- `birst_list_account_groups` - List account groups
- `birst_list_space_groups` - List space groups
## Installation
```bash
npm install
```
## Configuration
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `BIRST_ENV` | Environment to use (TST, PRD, TRN) | TST |
| `BIRST_IONAPI_PATH` | Custom path to .ionapi file | Auto-detected |
| `BIRST_LOG_LEVEL` | Log level (debug, info, warn, error) | info |
| `BIRST_ENABLE_GENAI` | Enable GenAI tools (requires Birst AI entitlement) | false |
| `BIRST_ENABLE_ICW` | Enable ICW query tools (requires app provisioning) | false |
### ION API Credentials
Place your `.ionapi` files in the project root or `credentials/` directory:
```
infor-birst-mcp/
├── TST.ionapi # Test environment
├── PRD.ionapi # Production environment
└── TRN.ionapi # Training environment
```
The `.ionapi` file is obtained from Infor Cloud Suite and contains OAuth2 credentials.
## Usage
### Development
```bash
npm run dev
```
### Production
```bash
npm run build
npm start
```
### Claude Code Configuration
Add to your Claude Code MCP settings:
```json
{
"mcpServers": {
"infor-birst": {
"command": "node",
"args": ["/path/to/infor-birst-mcp/dist/index.js"],
"env": {
"BIRST_ENV": "TST"
}
}
}
}
```
Or for development:
```json
{
"mcpServers": {
"infor-birst": {
"command": "npx",
"args": ["tsx", "/path/to/infor-birst-mcp/src/index.ts"],
"env": {
"BIRST_ENV": "TST"
}
}
}
}
```
## Example Usage
Once configured, you can use the tools in Claude:
```
"List all my Birst spaces"
→ Uses birst_list_spaces
"Show me reports in this space"
→ Uses birst_list_reports
"What workflows are scheduled to run?"
→ Uses birst_list_workflows with filter=isScheduled
"Who has access to this space?"
→ Uses birst_list_space_users
```
With GenAI enabled (`BIRST_ENABLE_GENAI=true`):
```
"Show me sales by region for 2024"
→ Uses birst_generate_bql + birst_execute_query
```
## Supported Environments
- **TST** - Test environment
- **PRD** - Production environment
- **TRN** - Training environment
Switch environments by setting the `BIRST_ENV` variable or using the default (TST).
## API Coverage
This MCP server interfaces with 3 Birst APIs:
| API | Endpoints | Description |
|-----|-----------|-------------|
| REST API | 156 | Space management, users, workflows |
| GenAI API | 3 | Natural language to BQL, chart generation |
| ICW API | 5 | Query execution and validation |
## Security
- Credentials are stored in `.ionapi` files (gitignored)
- OAuth2 tokens are automatically refreshed
- All API calls are authenticated via Bearer token
- Sensitive data is never logged
## License
MIT
