Heimdall Heimdall

• 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.

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/.

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

MIT

# 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

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"
      ]
    }
  }
}

• Configuration
• Tools

• 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.

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

# 公開匯入 smoke test
uv run python tests/test_imports.py

# 單元測試（模擬 HTTP，無需連接真實 API）
uv run python -m pytest tests/test_all_tools.py -v

# 編譯原始碼與測試
uv run python -m compileall src tests

# 建置 source distribution 與 wheel
uv build

從本機 checkout 執行時，將下列內容新增到你的 MCP 客戶端組態中（例如 Claude Desktop claude_desktop_config.json）：

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

或使用 .env 檔案：

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

• 設定
• 工具

• 這個 server 只暴露只讀 MCP 工具。
• server 會以設定的 HEIMDALL_API_TOKEN 權限呼叫 Heimdall API。
• Heimdall 寫入 API 不會透過此 MCP server 暴露。
• 公開文件刻意不連結私有後端 API 文件。