@tallistr/mcp

Standalone MCP (Model Context Protocol) server for CO2e emission tracking — exposes Tallistr data to LLM agents like Claude, GitHub Copilot, and Cursor.

Built by Tallistr AB (tallistr.com), this package helps companies connect AI assistants directly to reliable emissions workflows: summaries, drilldowns, supplier views, and explainability for audit and reporting.

Use @tallistr/mcp when you want to:

• Connect AI tools to your emissions data with no custom backend integration
• Let assistants answer climate-accounting questions with live tenant/company context
• Automate sustainability analysis using standard MCP tools and resources

Organizational Model

• Tenant: a group of companies in one Tallistr workspace
• Legal Entity: a single company within that tenant

Most tools either list tenants, or operate inside one tenant with optional legal-entity filtering.

Installation

npm install -g @tallistr/mcp

Quick Start

# 1) Authenticate once (OAuth2 Device flow)
tallistr-mcp auth login

# STDIO transport (default — for Claude Desktop, VS Code, Cursor)
tallistr-mcp

# HTTP transport on localhost
tallistr-mcp --transport http --port 3100

# HTTP with API key (required for non-loopback interfaces)
tallistr-mcp --transport http --host 0.0.0.0 --port 3100 --api-key <key>

Authentication

@tallistr/mcp supports the same OAuth2 flows as the CLI, including Device Authorization Grant and refresh tokens.

# Device flow (recommended for MCP users)
tallistr-mcp auth login

# Browser + PKCE flow
tallistr-mcp auth login --browser

# Check current auth status
tallistr-mcp auth status

# Clear credentials
tallistr-mcp auth logout

Startup sign-in behavior

When you start tallistr-mcp without valid credentials:

• In an interactive terminal: the server asks whether to start device login immediately.
• In non-interactive environments (for example IDE-launched stdio): startup fails fast with guidance to run tallistr-mcp auth login first or set TALLISTR_TOKEN.

Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "tallistr": {
      "command": "tallistr-mcp",
      "env": {
        "TALLISTR_TOKEN": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "TALLISTR_API_URL": "https://api.tallistr.com"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "tallistr": {
      "type": "stdio",
      "command": "tallistr-mcp"
    }
  }
}

Cursor

Add to Cursor MCP settings:

{
  "mcpServers": {
    "tallistr": {
      "command": "tallistr-mcp",
      "env": {
        "TALLISTR_TOKEN": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      }
    }
  }
}

Available Tools

| Tool | Description | | ------------------------ | ---------------------------------------- | | query_emissions | Aggregate CO2e by scope/period | | get_emission_drilldown | Detailed line items with pagination | | explain_receipt | Receipt calculation methodology | | explain_voucher | Voucher emission breakdown | | list_suppliers | Canonical suppliers for a tenant | | list_legal_entities | Legal entities for a tenant | | list_tenants | Tenants accessible to authenticated user | | check_health | API connectivity and config health |

Available Resources

| URI | Description | | ------------------------------------------------- | --------------------- | | tallistr://tenants | Tenant list | | tallistr://tenants/{tenantId}/legal-entities | Legal entities | | tallistr://tenants/{tenantId}/emissions/summary | YTD emission summary | | tallistr://taxonomy/emission-categories | GHG category taxonomy | | tallistr://taxonomy/scopes | GHG Protocol scopes |

Environment Variables

| Variable | Description | | --------------------- | ---------------------------------------------------------- | | TALLISTR_API_URL | Backend API base URL (default: https://api.tallistr.com) | | TALLISTR_TOKEN | Bearer token for authentication | | TALLISTR_TENANT_ID | Default tenant ID | | TALLISTR_CONFIG_DIR | Override config directory (default: XDG) | | TALLISTR_DEBUG | Enable debug logging and detailed stack traces (1 or true) |

Command-Line Options

| Option | Description | | ------------------------ | ----------------------------------------- | | --transport <protocol> | Transport: stdio (default) or http | | --port <number> | HTTP port (default: 3100) | | --host <address> | HTTP host (default: 127.0.0.1) | | --api-key <key> | API key for HTTP transport authentication | | --version | Print version | | --help | Show help |

Authentication Commands

| Command | Description | | ----------------------------------- | -------------------------------------- | | tallistr-mcp auth login | Start OAuth2 Device Authorization flow | | tallistr-mcp auth login --browser | Start browser PKCE flow | | tallistr-mcp auth status | Show auth source and expiry | | tallistr-mcp auth logout | Clear stored credentials and defaults |

Requirements

• Node.js >= 22

Related

• @tallistr/cli — Interactive CLI for CO2e emission tracking