@tallistr/mcp

Standalone MCP (Model Context Protocol) server for Tallistr climate-accounting data — exposes live Tallistr tools and resources 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, sourcing analysis, receipts search, vouchers, reports, and explainability for audit and reporting.

Tallistr converts operational finance and travel data into explainable CO2e calculations. The MCP server lets an agent ask questions such as “how much did we emit?”, “which suppliers drive the most spend or CO2e?”, and “why was this receipt calculated this way?” without any custom integration work.

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

Typical agent questions:

• “Which tenant and legal entity should I use for this analysis?”
• “How much did this group emit this year, and which scope dominates?”
• “Which suppliers or categories drive the most spend or CO2e?”
• “Which receipts mention this supplier, route, or invoice number?”
• “Why did Tallistr calculate this receipt or voucher this way?”

Organizational Model

• Tenant: a Tallistr workspace, usually representing a group of companies or a parent organization
• Legal Entity: one company inside that tenant

Most tools either list tenants, or operate inside one tenant with optional legal-entity filtering. In other words: pick the group first, then optionally narrow to a specific company.

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 | Best for answering | | ------------------------------ | ------------------------------------------------------------------ | | list_tenants | “Which Tallistr workspaces or company groups can I access?” | | list_legal_entities | “Which companies exist inside this tenant?” | | query_emissions | “How much did this tenant or company emit in this period?” | | get_emission_drilldown | “Which detailed records drove these emissions?” | | explain_receipt | “Why was this receipt calculated this way?” | | explain_voucher | “Why was this voucher calculated this way?” | | list_suppliers | “Which canonical suppliers does Tallistr know for this tenant?” | | check_health | “Is the Tallistr integration ready for use?” | | get_sourcing_kpis | “What does our spend profile look like overall?” | | get_sourcing_categories | “Which spend categories are largest?” | | get_category_suppliers | “Which suppliers dominate this spend category?” | | get_sourcing_suppliers | “Which suppliers account for the most spend?” | | get_supplier_categories | “What categories make up this supplier's spend?” | | get_co2e_sourcing_kpis | “What does our sourcing footprint look like overall?” | | get_co2e_scope_breakdown | “How is CO2e distributed across scopes and categories?” | | get_co2e_sourcing_categories | “Which categories contribute the most CO2e?” | | get_co2e_sourcing_suppliers | “Which suppliers contribute the most CO2e?” | | get_co2e_sourcing_drilldown | “Which detailed records sit behind this sourcing footprint?” | | list_receipts | “Which receipts match these structured filters?” | | search_receipts | “Which receipts mention this text, supplier, route, or reference?” | | get_receipt | “Show me this specific receipt.” | | get_report_summary | “How many reports do we have and what do they cover?” | | list_reports | “Which reports match these dates or search terms?” | | get_report | “Show me this specific report.” | | list_vouchers | “Which vouchers are available for this tenant or company?” | | get_voucher | “Show me this specific voucher.” |

Available Resources

| URI | Best for reading | | --------------------------------------------------- | --------------------------------------------------------- | | tallistr://tenants | Available tenants/workspaces or company groups | | tallistr://tenants/{tenantId}/legal-entities | Companies inside a tenant | | tallistr://tenants/{tenantId}/emissions/summary | Current year-to-date emissions snapshot | | tallistr://tenants/{tenantId}/sourcing/categories | Spend-based category analytics | | tallistr://tenants/{tenantId}/sourcing/suppliers | Spend-based supplier analytics | | tallistr://tenants/{tenantId}/receipts/search | Search-driven receipt result sets | | tallistr://tenants/{tenantId}/vouchers | Voucher lists for a tenant or filtered company | | tallistr://taxonomy/emission-categories | Reference taxonomy for emission categories | | tallistr://taxonomy/scopes | Reference taxonomy for GHG Protocol scopes and sub-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> | stdio for IDE or desktop agents, http for explicit MCP clients or services | | --port <number> | HTTP port when serving over HTTP (default: 3100) | | --host <address> | HTTP bind address; keep 127.0.0.1 unless you want remote clients | | --api-key <key> | API key for HTTP transport; required for non-local bind addresses | | --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 |

Development

The published build output is obfuscated (minified with variable mangling) via minify: true in tsup.config.ts. Do not disable this unless explicitly required.

Requirements

• Node.js >= 22

Related

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