MCP Heimdall
asgard-ai-platform/mcp-heimdall
Acesso seguro e estruturado ao CMS Asgard via MCP
Ver no GitHubServidor MCP que expõe ferramentas somente leitura para a plataforma de gerenciamento de conteúdo Asgard. Fornece 26 ferramentas para acessar recursos como artigos, avatares, contas, aplicativos, missões, publicações e tópicos através de autenticação por token bearer.
Instalação
npx convez-ai asgard-ai-platform/mcp-heimdall1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar Claude com plataforma de conteúdo Asgard
- Consultar dados de artigos, missões e publicações programaticamente
- Automatizar fluxos que envolvem leitura de conteúdo gerenciado
Veredito

MCP server bem estruturado e documentado para integração com Asgard CMS. Abordagem read-only apropriada para segurança, embora escopo seja bastante específico ao ecossistema Asgard.
README
A tradução para o português deste README ainda está na fila.
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
| Environment Variable | Required | Default | Description |
|---|---|---|---|
HEIMDALL_API_TOKEN | Yes | — | Bearer token for the API |
HEIMDALL_API_BASE_URL | No | https://heimdall-api.asgard-ai.com | API base URL override |
Tools (26)
All workspace-scoped tools require a workspace_id parameter.
Use list_workspaces first to discover available workspace IDs.
Workspace
| Tool | Description | Parameters |
|---|---|---|
list_workspaces | List all workspaces for the current user | — |
get_workspace | Get a workspace by ID | workspace_id |
Article
| Tool | Description | Parameters |
|---|---|---|
list_articles | List articles in a workspace | workspace_id, page, size |
get_article | Get an article by ID | workspace_id, article_id |
Article Template
| Tool | Description | Parameters |
|---|---|---|
list_article_templates | List article templates in a workspace | workspace_id, page, size |
get_article_template | Get an article template by ID | workspace_id, article_template_id |
Avatar
| Tool | Description | Parameters |
|---|---|---|
list_avatars | List avatars in a workspace | workspace_id, page, size, name*, gender* |
get_avatar | Get an avatar by ID | workspace_id, avatar_id |
Account (Platform Account)
| Tool | Description | Parameters |
|---|---|---|
list_accounts | List platform accounts in a workspace | workspace_id, page, size, provider_type*, app_id* |
get_account | Get a platform account by ID | workspace_id, account_id |
get_accounts_by_avatar | Get all accounts linked to an avatar | workspace_id, avatar_id |
App (OAuth App)
| Tool | Description | Parameters |
|---|---|---|
list_apps | List OAuth apps in a workspace | workspace_id, page, size, provider_type* |
get_app | Get an OAuth app by ID | workspace_id, app_id |
Blob
| Tool | Description | Parameters |
|---|---|---|
list_blobs | List blob records in a workspace | workspace_id, page, size, filter_by*, filter_value* |
Content Source
| Tool | Description | Parameters |
|---|---|---|
list_content_sources | List content sources in a workspace | workspace_id, page, size |
get_content_source | Get a content source by ID | workspace_id, content_source_id |
Mission
| Tool | Description | Parameters |
|---|---|---|
list_missions | List missions in a workspace | workspace_id, page, size, topic_id*, avatar_id*, mission_type*, q*, sort_by*, sort_order* |
get_mission | Get a mission by ID | workspace_id, mission_id |
export_mission | Export a mission with all its contents | workspace_id, mission_id |
Mission Content
| Tool | Description | Parameters |
|---|---|---|
list_mission_contents | List mission contents in a workspace | workspace_id, page, size, mission_id*, avatar_id*, status* |
get_mission_content | Get a mission content by ID | workspace_id, mission_content_id |
Publication
| Tool | Description | Parameters |
|---|---|---|
list_publications | List publications in a workspace | workspace_id, page, size |
get_publication | Get a publication by ID | workspace_id, publication_id |
Topic
| Tool | Description | Parameters |
|---|---|---|
list_topics | List topics in a workspace | workspace_id, page, size, name* |
get_topic | Get a topic by ID | workspace_id, topic_id |
list_topic_categories | List all available topic categories | workspace_id |
* 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
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