MCP Heimdall

Heimdall — an MCP (Model Context Protocol) server that exposes read-only tools for Asgard's content management platform.

Provides list and get tools for all major resources: articles, blobs, content sources, article templates, avatars, accounts, apps, missions, mission contents, publications, topics, and workspaces.

繁體中文

Part of the Asgard AI Platform open-source ecosystem.

What This Does

• 26 MCP tools covering workspace, article, avatar, account, app, blob, content source, mission, publication, and topic resources
• Read-only tool surface for safe AI assistant access
• Bearer token authentication through HEIMDALL_API_TOKEN
• Public-safe configuration through environment variables and .env.example
• stdio transport for local MCP clients

See docs/tools.md for the full public tool reference.

Quick Start

Install

pip install mcp-heimdall

Run with uvx without installing globally:

uvx --from mcp-heimdall mcp-heimdall

For local development:

git clone https://github.com/asgard-ai-platform/mcp-heimdall.git
cd mcp-heimdall
uv sync

Set your API token:

export HEIMDALL_API_TOKEN=your_bearer_token_here

For local development, copy .env.example to .env and set HEIMDALL_API_TOKEN. HEIMDALL_API_BASE_URL is optional unless you need an override.

See docs/configuration.md for details.

Use with Claude Code

After installing the package and configuring environment variables, add the stdio MCP server:

claude mcp add --transport stdio heimdall -- mcp-heimdall

For a local checkout:

claude mcp add --transport stdio heimdall -- uv --directory /path/to/mcp-heimdall run mcp-heimdall

Use with Claude Desktop

Package install / uvx example:

{
  "mcpServers": {
    "heimdall": {
      "command": "uvx",
      "args": ["mcp-heimdall"],
      "env": {
        "HEIMDALL_API_TOKEN": "your_bearer_token_here"
      }
    }
  }
}

For a local checkout, run it through uv from the repository directory:

{
  "mcpServers": {
    "heimdall": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-heimdall", "mcp-heimdall"],
      "env": {
        "HEIMDALL_API_TOKEN": "your_bearer_token_here"
      }
    }
  }
}

More examples are available in examples/.

Test

# Public import smoke test
uv run python tests/test_imports.py

# Unit tests (mocked HTTP, no live API needed)
uv run python -m pytest tests/test_all_tools.py -v

# Compile source and tests
uv run python -m compileall src tests

# Build source distribution and wheel
uv build

Configuration

Tools (26)

All workspace-scoped tools require a workspace_id parameter.
Use list_workspaces first to discover available workspace IDs.

Workspace

Article

Article Template

Avatar

Account (Platform Account)

App (OAuth App)

Blob

Content Source

Mission

Mission Content

Publication

Topic

* optional filter parameter

MCP Client Configuration

Add this to your MCP client config (e.g. Claude Desktop claude_desktop_config.json) when running from a local checkout:

{
  "mcpServers": {
    "heimdall": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-heimdall", "mcp-heimdall"],
      "env": {
        "HEIMDALL_API_TOKEN": "your_bearer_token_here"
      }
    }
  }
}

Or with a .env file:

{
  "mcpServers": {
    "heimdall": {
      "command": "uv",
      "args": [
        "run",
        "--env-file", "/path/to/mcp-heimdall/.env",
        "--directory", "/path/to/mcp-heimdall",
        "mcp-heimdall"
      ]
    }
  }
}

Documentation

• Configuration
• Tools

Boundaries

• The server exposes read-only MCP tools only.
• The server operates with the permissions of the configured HEIMDALL_API_TOKEN.
• Heimdall write APIs are intentionally not exposed through this MCP server.
• Public documentation intentionally avoids linking to private backend API documents.

Architecture

stdio (JSON-RPC 2.0)
  → mcp-heimdall (console script entry point)
    → src/mcp_heimdall/server.py       — entry point, imports trigger tool registration
      → src/mcp_heimdall/app.py        — MCPServer singleton (FastMCP "mcp-heimdall")
        → src/mcp_heimdall/tools/*     — @mcp.tool() decorated functions
          → src/mcp_heimdall/connectors/rest_client.py  — HTTP client with retry + extra_headers support
            → src/mcp_heimdall/auth/bearer.py           — reads HEIMDALL_API_TOKEN env var
              → src/mcp_heimdall/config/settings.py     — base URL + endpoint map

License

MIT