# AntonioTF5/soul-mcp-server [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/AntonioTF5/soul-mcp-server  
**GitHub Stars:** 2  
**npm Downloads (last month):** 337  
**Views:** 10  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/antoniotf5-soul-mcp-server

## Description
Validate and generate SOUL.md agent identity files from Claude Desktop. SOUL.md is the open format for persistent AI agent identity — personality, voice, values, and behavioral constraints in a machine-readable YAML file.

## Tools
Capabilities this server exposes over MCP:

- **validate_soul_file** — Validates a `.soul.md` file against the SOUL.md schema.
- **generate_soul_template** — Generates a starter `.soul.md` for a given agent name and keywords.
- **score_soul_file** — Returns a completeness score (0–100) based on how many optional fields are filled.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "soul-mcp-server": {
    "command": "npx",
    "args": ["soul-mcp-server"]
  }
}
```

## Documentation

## What AntonioTF5/soul-mcp-server MCP server does

AntonioTF5/soul-mcp-server MCP server exposes three operations for the SOUL.md format. It can check whether a `.soul.md` file conforms to the SOUL.md schema, create a starter file for a new agent, and estimate how complete an existing file is.

The server is aimed at agent identity files that describe characteristics such as personality, voice, values, and behavioral constraints. It works through MCP, so an MCP client can invoke these operations from a conversational workflow instead of requiring a separate command-line validation step.

## How it works

The validation and scoring tools accept a file path. `validate_soul_file` checks the referenced file against the schema and returns JSON containing a pass indicator, the detected name and version, and any validation errors. `score_soul_file` examines the optional fields and returns a numeric score from 0 to 100, along with counts or lists for filled, missing, and total fields.

`generate_soul_template` does not require an existing file path. Provide an agent name and, optionally, an array of domain keywords. The result is a ready-to-edit SOUL file returned as a string. For example, keywords related to carbon capture can seed a template for a climate-focused agent.

## Setup and configuration

The README shows a local stdio configuration for Claude Desktop. Add an MCP server entry to `claude_desktop_config.json` and use `npx` to run the `soul-mcp-server` package:

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

After restarting Claude Desktop, the three tools should be available. The documented macOS configuration path is `~/Library/Application Support/Claude/claude_desktop_config.json`. The setup instructions do not specify environment variables, API keys, or other credentials.

## Tools and capabilities

- `validate_soul_file`: accepts a required `path` string and reports schema validation status, file name, version, and errors.
- `generate_soul_template`: accepts a required `name` string and optional `keywords` string array, then returns starter file content.
- `score_soul_file`: accepts a required `path` string and reports a 0–100 completeness score plus filled, missing, and total field information.

The tools can be used to validate an existing identity file, create an initial draft, or identify unfilled optional sections before further editing. The project also references the separate SOUL.md specification, example soul files, and a CLI validator that can operate without Claude; those are related resources rather than capabilities described for this MCP server.

## Limitations and notes

AntonioTF5/soul-mcp-server MCP server is documented for validation, template generation, and completeness scoring. The material does not describe tools for deploying an agent, hosting a file, editing a file in place, or serving a live agent subdomain. Template generation returns content as a string, so the client or user must handle saving or editing that output.

A completeness score reflects how many optional fields are filled; it is not described as a measure of writing quality, behavioral correctness, or runtime agent performance. Validation depends on the referenced file path being available to the local server process. The README identifies the project as MIT-licensed and says it can be used from Claude Desktop or another MCP-compatible client.

_Full upstream README: https://allmcps.com/mcp/antoniotf5-soul-mcp-server/readme_