allstacks-mcp 0.1.4

MCP server for Allstacks API - provides AI-ready interface to Allstacks metrics, projects, and analytics

Allstacks MCP Server

A comprehensive Model Context Protocol (MCP) server providing AI-ready access to the Allstacks API. Authenticate with either HTTP Basic (username + password) or a Bearer Personal Access Token.

Overview

This MCP server exposes 194+ tools organized into 12 categories for comprehensive interaction with Allstacks:

Tool Categories

1. Metrics & Analytics (20 tools): GMDTS data, Metrics V2 (including capitalization preview), templates, insight configs, population benchmarks, company metrics
2. Service Items & Work Items (18 tools): Complete CRUD for work items, parent service items, property keys, estimation methods, notes, filter sets
3. Users & Teams (20 tools): Full user management, invites, roles, team tags, personal access tokens, service users
4. Organization & Projects (31 tools): Organizations, projects, settings, services, calendars, time periods, slots, capitalization reports (V2)
5. Dashboards & Widgets (18 tools): Complete dashboard/widget CRUD, shared links, cloning, widget management
6. Employee Analytics (8 tools): Employee metrics, cohorts, work items, timeline, summary, periods
7. Forecasting & Planning (10 tools): V3 forecasts, velocity, scenarios, capacity planning, chart analysis
8. Labels & Tagging (15 tools): Labels, label families, bulk operations, service item label assignment
9. Alerts & Monitoring (14 tools): Alert rules, active alerts, notifications, subscriptions, preferences
10. AI & Intelligence (16 tools): AI reports, Action AI code query, metric builder, AI metric builder (project), pattern analysis, surveys, DX scores, AI tool usage
11. Work Bundles (12 tools): Selectable work bundle management, forecasting, metrics, cloning
12. Risk Management (12 tools): Risk definitions, project risks, assessment, trends, resolution

Project Structure

allstacks-mcp-server/
├── allstacks_mcp/
│   ├── __init__.py
│   ├── __main__.py             # python -m allstacks_mcp entry point
│   ├── server.py               # Main entry — 194+ tools, arg parsing
│   ├── client.py               # HTTP client (Basic + Bearer auth)
│   └── tools/                  # Tool modules by category
│       ├── __init__.py
│       ├── metrics.py          # 20 metrics tools
│       ├── service_items.py    # 18 service item tools
│       ├── users_teams.py      # 20 user/team tools
│       ├── org_projects.py     # 31 org/project tools
│       ├── dashboards.py       # 18 dashboard tools
│       ├── employee.py         # 8 employee analytics tools
│       ├── forecasting.py      # 10 forecasting tools
│       ├── labels.py           # 15 label management tools
│       ├── alerts.py           # 14 alert/monitoring tools
│       ├── ai_analytics.py     # 16 AI & analytics tools
│       ├── work_bundles.py     # 12 work bundle tools
│       └── risk_management.py  # 12 risk management tools
├── pyproject.toml
├── uv.lock
└── README.md

Quick Start

Prerequisites

• Python 3.10 or higher
• uv package manager (curl -LsSf https://astral.sh/uv/install.sh | sh)
• Allstacks account with either:
  • Personal Access Token (PAT) from the Allstacks UI — recommended for all users, required for SSO
  • Username + password (only for local accounts, not SSO)

Installation

The simplest way to use the Allstacks MCP server is via uvx, which installs and runs the server in one command:

Option A — Bearer auth with Personal Access Token (recommended):

uvx allstacks-mcp --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/

Option B — HTTP Basic auth (local accounts only):

uvx allstacks-mcp --username [e-mail] --password your-password --base-url https://app.allstacks.com/api/v1/

That's it! The server will start and be ready to accept MCP connections.

For local development or contributing to this project, see the Local Development section below.

Authentication & Security

Authentication Modes

The server supports two authentication modes. Pick one — they are mutually exclusive.

Option A — Bearer auth with a Personal Access Token (recommended; required for SSO users)

Generate a PAT in the Allstacks UI under Personal Access Tokens and pass it with --token:

uvx allstacks-mcp --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/

• ✅ Works for all users, including SSO-only accounts
• ✅ Tokens can be revoked from the UI without changing account credentials
• ✅ More secure than password-based auth
• Token is sent as Authorization: Bearer <token>

Option B — HTTP Basic auth with username + password

Only works for local accounts that have a password set. SSO-only users will get a 401 error.

uvx allstacks-mcp --username [e-mail] --password your-password --base-url https://app.allstacks.com/api/v1/

• ⚠️ Only for local accounts (not SSO users)
• Credentials are sent using HTTP Basic authentication

Base URL: The default is https://app.allstacks.com/api/v1/. Override with --base-url if your deployment uses a different endpoint.

🔒 Security Best Practices

Credential Management

⚠️ IMPORTANT: Your credentials provide full access to your Allstacks account.

1. Prefer Personal Access Tokens over passwords — revocable, scoped, and the only option for SSO users.

2. Use Environment Variables when possible

   export ALLSTACKS_TOKEN="your-pat"
   # or, for Basic auth:
   export ALLSTACKS_USERNAME="your-username"
   export ALLSTACKS_PASSWORD="your-password"
   

3. Never commit credentials to version control

   • The MCP client config file may contain credentials
   • Keep config files in .gitignore

4. Rotate credentials regularly for enhanced security

Process Security

Note: Command-line arguments (--username, --password, --token) are visible in process lists. For production use:

• Use environment variables
• Use secure configuration files
• Consider using a secrets management system

Data Access & Privacy

This MCP server acts as a pass-through to the Allstacks API:

• ✅ Does not store or log your credentials
• ✅ Does not cache API responses
• ✅ Does not persist any data locally
• ✅ Returns API data as-is without modification

AI Access: When used with AI assistants (e.g., Claude), the AI will have access to:

• All data accessible via your Allstacks credentials
• The same permissions as your Allstacks user account
• Ability to create, modify, and delete resources (depending on your permissions)

Recommendation: Consider using a dedicated Allstacks account with limited permissions for AI access.

Usage

Running the Server Standalone

Bearer / PAT (recommended; required for SSO users):

uvx allstacks-mcp --token YOUR_PAT

Basic / username + password (local accounts only):

uvx allstacks-mcp --username YOUR_USERNAME --password YOUR_PASSWORD

Command-line options:

• --token or -t: Personal Access Token for Bearer auth (alternative to username/password)
• --username or -u: Username for HTTP Basic auth (paired with --password)
• --password or -p: Password for HTTP Basic auth (paired with --username)
• --base-url or -b: Override the default API base URL (default: https://app.allstacks.com/api/v1/)

Pass either --token OR both --username and --password — not both modes at once.

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop's claude_desktop_config.json or Claude Code's mcp.json).

Recommended — PAT / Bearer auth (works for all users, including SSO):

{
    "mcpServers": {
        "allstacks": {
            "command": "uvx",
            "args": [
                "allstacks-mcp",
                "--token",
                "YOUR_PERSONAL_ACCESS_TOKEN",
                "--base-url",
                "https://app.allstacks.com/api/v1/"
            ]
        }
    }
}

Alternative — Username + password (local accounts only):

{
    "mcpServers": {
        "allstacks": {
            "command": "uvx",
            "args": [
                "allstacks-mcp",
                "--username",
                "[e-mail]",
                "--password",
                "your-password",
                "--base-url",
                "https://app.allstacks.com/api/v1/"
            ]
        }
    }
}

Important Notes:

• Replace YOUR_PERSONAL_ACCESS_TOKEN with your actual PAT from the Allstacks UI
• Or replace [e-mail] and your-password with your credentials (local accounts only)
• The --base-url is optional (defaults to https://app.allstacks.com/api/v1/)
• uvx automatically installs and runs the latest version from PyPI — no manual installation needed!

Using a local clone for development? See the Local Development section for the configuration pattern.

Features

Comprehensive API Coverage

All tools are verified against the official Allstacks OpenAPI specification:

• ✅ All endpoints use correct paths and parameters
• ✅ Detailed parameter descriptions from official API docs
• ✅ Proper error handling and validation
• ✅ HTTP Basic Auth support
• ✅ Async/await for performance

Modular Architecture

Tools are organized into logical categories matching the Allstacks API structure:

• Easy to navigate and understand
• Clear separation of concerns
• Consistent patterns across all tools
• Well-documented with OpenAPI references

Rich Tool Descriptions

Every tool includes:

• Purpose and use case
• Required and optional parameters
• Expected return formats
• OpenAPI endpoint reference
• Example usage patterns

Example Tool Usage

Get GMDTS Metrics Data

# Get Generated Metric Data Time Series (GMDTS)
get_gmdts_data(
    project_id=123,
    metric_type="Velocity",
    start_date=1704067200000,
    end_date=1706745600000
)

List Work Items with Filtering

# List service items with filtering
list_service_items(
    item_type="CARD",
    limit=100,
    offset=0
)

Create AI Report

# Generate AI analysis report
create_ai_report(
    org_id=456,
    report_type="project_health",
    project_id=123
)

Forecast Work Bundle

# Get Monte Carlo forecast for work bundle
get_work_bundle_forecast(
    project_id=123,
    bundle_id=789,
    confidence_level=80
)

API Compatibility

This server is built against the official Allstacks API v1 specification and includes:

• Non-admin endpoints only (no destructive operations)
• Full CRUD for resources where appropriate
• Bulk operations for efficiency
• Proper pagination support
• Query parameter validation

Local Development

If you want to contribute to this project or run from a local clone instead of PyPI:

Setup

1. Clone the repository:

   git clone https://github.com/allstacks/allstacks-mcp-server.git
   cd allstacks-mcp-server
   

2. Install dependencies:

   uv sync
   

Running from Local Clone

Bearer / PAT (recommended):

uv run python -m allstacks_mcp.server --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/

Username + password (local accounts only):

uv run python -m allstacks_mcp.server --username YOUR_USERNAME --password YOUR_PASSWORD --base-url https://app.allstacks.com/api/v1/

MCP Client Configuration (Local Clone)

For Claude Desktop or Claude Code, use this configuration pattern when working with a local clone:

{
    "mcpServers": {
        "allstacks": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/allstacks-mcp-server",
                "run",
                "python",
                "-m",
                "allstacks_mcp.server",
                "--token",
                "YOUR_PAT",
                "--base-url",
                "https://app.allstacks.com/api/v1/"
            ]
        }
    }
}

Replace /ABSOLUTE/PATH/TO/allstacks-mcp-server with the full path to your cloned repository.

Development

Adding New Tools

1. Create or update a tool file in allstacks_mcp/tools/
2. Follow the existing pattern for tool registration
3. Include full docstrings with OpenAPI references
4. Add the module to allstacks_mcp/tools/__init__.py
5. Register it in allstacks_mcp/server.py's register_all_tools() function

Testing

When working on the codebase, run the server in development mode:

# From local clone with Bearer token
uv run python -m allstacks_mcp.server --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/

# Or with a dev/staging environment
uv run python -m allstacks_mcp.server --token YOUR_PAT --base-url https://api-dev.allstacks.com/api/v1/

License

MIT

Support

For issues or questions about the Allstacks API, contact the Allstacks team. For issues specific to this MCP server, please file an issue in the repository.