English Français العربية

io.github.AntonioTF5/soul-mcp-server

Official registry AI and agents

MCP server for validating and generating SOUL.md agent identity files from Claude Desktop.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package soul-mcp-server
Claude Code 
claude mcp add soul-mcp-server -- npx -y soul-mcp-server@1.0.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "soul-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "soul-mcp-server@1.0.0"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. soul-mcp-server
  2. 30-second setup
  3. Tools
  4. Spec & examples

soul-mcp-server

MCP server for SOUL.md — validate and generate soul files directly from Claude Desktop or any MCP-compatible client.

Built for Agenturo — the reference SOUL.md implementation. Deploy your soul file as a live agent on your own subdomain.

30-second setup

Add this to your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "soul-md-cli": {
      "command": "npx",
      "args": ["soul-mcp-server"]
    }
  }
}

Restart Claude Desktop. The three soul tools will appear in your tool list.

Tools

validate_soul_file

Validates a .soul.md file against the SOUL.md schema.

Parameters:

  • path (string, required) — path to the soul file

Returns: JSON with pass boolean, name, version, and errors array.

Example prompt:

"Validate my soul file at ~/agents/marcus.soul.md"

generate_soul_template

Generates a starter .soul.md for a given agent name and keywords.

Parameters:

  • name (string, required) — the agent's name
  • keywords (string[], optional) — domain keywords to seed the template

Returns: A ready-to-edit soul file as a string.

Example prompt:

"Generate a soul template for a climate scientist who specializes in carbon capture"

score_soul_file

Returns a completeness score (0–100) based on how many optional fields are filled.

Parameters:

  • path (string, required) — path to the soul file

Returns: JSON with score, filled, missing, and total.

Example prompt:

"Score my agent at ~/agents/startup-advisor.soul.md and tell me what's missing"

Spec & examples

Full specification: soul-spec

Curated community soul files: awesome-soul-files

CLI validator (no Claude required): soul-md-cli

MIT License. Created by Anton Agafonov.

Frequently asked questions

What is io.github.AntonioTF5/soul-mcp-server?

MCP server for validating and generating SOUL.md agent identity files from Claude Desktop.

How do I install io.github.AntonioTF5/soul-mcp-server?

It runs on your machine. In Claude Code: claude mcp add soul-mcp-server -- npx -y soul-mcp-server@1.0.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.AntonioTF5/soul-mcp-server need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is io.github.AntonioTF5/soul-mcp-server open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.AntonioTF5/soul-mcp-server?

It is published by AntonioTF5. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.