Content
# Planning Analytics MCP Server Suite
Natural language querying and interactive visualization for **IBM Planning Analytics / TM1** via the [Model Context Protocol](https://modelcontextprotocol.io).
Works with **any TM1 deployment** — on-premise, IBM Cloud, or Planning Analytics as a Service. Unlike IBM's official `pa-cube-mcp` tools (which require PAaaS + watsonx Orchestrate), this suite connects directly to the TM1 REST API via TM1py.
## What's in here
| Package | Language | Transport | Purpose |
|---------|----------|-----------|---------|
| [`planning_analytics_mcp`](planning_analytics_mcp/) | Python 3.10+ | stdio | Core data server — query cubes, browse dimensions, execute MDX |
| [`planning_analytics_mcp_app`](planning_analytics_mcp_app/) | Node.js 18+ | Streamable HTTP | Optional UI layer — interactive tables, charts, dashboards |
The data server works standalone. Add the App server when you want query results rendered as interactive views inside Claude Desktop, ChatGPT, or other MCP hosts that support the [MCP Apps extension](https://apps.extensions.modelcontextprotocol.io/).
## Architecture
```
┌──────────────────────────────────────────────────────────┐
│ MCP Host (Claude Desktop / ChatGPT / Cursor / VS Code) │
│ │
│ ┌───────────────────┐ ┌─────────────────────────┐ │
│ │ Data Server │ │ App Server │ │
│ │ (Python, stdio) │ │ (Node.js, HTTP :3001) │ │
│ │ │ │ │ │
│ │ pa_list_cubes │ │ pa_app_explore_cubes │ │
│ │ pa_execute_mdx │ │ pa_app_show_mdx_results│ │
│ │ pa_query_cube │ │ pa_app_dashboard │ │
│ │ ...8 tools │ │ ...3 interactive views │ │
│ └─────────┬─────────┘ └─────────────────────────┘ │
└─────────────┼─────────────────────────────────────────────┘
│ TM1py
▼
TM1 REST API (OData v4)
│
▼
IBM Planning Analytics / TM1
```
The LLM uses the Python tools to fetch data, then optionally passes results to the App tools for visual display.
## Quick start
### 1. Data server (required)
```bash
cd planning_analytics_mcp
pip install -e .
export TM1_ADDRESS="your-tm1-server"
export TM1_PORT="8010"
export TM1_USER="admin"
export TM1_PASSWORD="your-password"
export TM1_SSL="true"
# verify the connection
PA_MCP_DEBUG=1 python -m planning_analytics_mcp.server
```
### 2. App server (optional)
```bash
cd planning_analytics_mcp_app
npm install
npm run build
PA_APP_PORT=3001 npm start
```
### 3. Register with your MCP host
`claude_desktop_config.json`:
```json
{
"mcpServers": {
"planning-analytics": {
"command": "planning-analytics-mcp",
"env": {
"TM1_ADDRESS": "your-tm1-server",
"TM1_PORT": "8010",
"TM1_USER": "admin",
"TM1_PASSWORD": "your-password",
"TM1_SSL": "true"
}
},
"planning-analytics-app": {
"url": "http://localhost:3001/mcp"
}
}
}
```
Restart your host, then ask: *"What cubes are available on the TM1 server?"*
## Documentation
- **[Getting Started Guide (Markdown)](docs/GETTING_STARTED.md)** — full setup for both servers, troubleshooting, environment reference
- **[Getting Started Guide (Word)](docs/Planning_Analytics_MCP_Getting_Started_Guide.docx)** — same content, formatted for printing/sharing
- [Data server README](planning_analytics_mcp/README.md)
- [App server README](planning_analytics_mcp_app/README.md)
## Tools
### Data server (`planning_analytics_mcp`)
| Tool | Description |
|------|-------------|
| `pa_list_cubes` | List cubes with metadata; filter by name, hide control cubes |
| `pa_get_cube_dimensions` | Dimensions, hierarchies, and member counts for a cube |
| `pa_get_dimension_members` | Members filtered by hierarchy, level, or parent |
| `pa_lookup_members` | Search dimension members by substring |
| `pa_execute_mdx` | Execute raw MDX and return formatted results |
| `pa_query_cube` | Cube context + MDX template for natural language questions |
| `pa_get_cube_sample_data` | Sample data with auto-generated MDX |
| `pa_server_info` | TM1 server name, version, configuration |
All tools are read-only and support both `markdown` and `json` response formats.
### App server (`planning_analytics_mcp_app`)
| Tool | View |
|------|------|
| `pa_app_explore_cubes` | Interactive cube tree with search and expandable dimensions |
| `pa_app_show_mdx_results` | Sortable table + bar/line/pie chart, CSV export, refresh |
| `pa_app_dashboard` | Multi-panel dashboard: KPI cards, charts, tables |
Every App tool includes a plain-text fallback, so hosts without MCP Apps support still get usable output.
## Requirements
- Python 3.10+ (data server)
- Node.js 18+ (app server, optional)
- Network access to your TM1 REST API
- TM1 credentials — user/password for on-prem, API key for cloud
## License
MIT — see [LICENSE](LICENSE).
