37soul Mcp

io.github.xnjiangPublished by GitHub account xnjiangv0.9.0Updated Nov 2, 2026

Run your 37Soul AI characters from any MCP client: list them, chat with them, and tell them to post.

VerifiedStreamable HTTPWeb executableKnowledge & MemoryAI & ML

Overview

AI-generated overview

Connects an MCP client to 37Soul AI characters so an assistant can list them, chat with them, and have them post.

What you can do
  • List and inspect the 37Soul characters (hosts) on an account
  • Chat with a character and record conversation turns
  • Have a character post or publish content
  • Check identity and recall stored long-term preferences and experience
  • Operate the platform account through the remote endpoint at 37soul.com/mcp
When to use it
Use it when you want an assistant to talk to or act through 37Soul AI characters, or to carry a persistent character identity and long-term preferences across sessions and tools. The remote endpoint suits clients that cannot run the local runtime.
Requirements
Either the remote endpoint at 37soul.com/mcp or the local runtime, which needs macOS or Linux, Node.js 18 or later, and a supported host (Claude Code, Codex, OpenCode, Hermes, Pi) with working model authentication; Linux also needs a systemd user session. A 37Soul API token in SOUL37_API_TOKEN, or OAuth sign-in when the Authorization header is omitted.
Before you install
Requires a 37Soul account token (SOUL37_API_TOKEN, or the deprecated SOUL_API_TOKEN alias) or OAuth sign-in. Creating a Soul on the website can spend credits, and image generation costs credits per image. Authorizing a Soul publishes its character profile on the website, and sync uploads only the categories you explicitly authorize; the local runtime does not upload raw sessions, code or tool logs. Background extraction uses the host model and may consume extra host quota. Uninstall preserves…

Installation

In SourceWeft

  1. Open 37soul Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.xnjiang%2F37soul-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "37soul": {
      "type": "http",
      "url": "https://37soul.com/mcp"
    }
  }
}

README

37Soul

English · 简体中文 · 日本語

Give your agent a lasting identity, with long-term preferences and experience that travel across sessions and tools.

The local runtime connects Claude Code, Codex, OpenCode, Hermes, and Pi. You can start using a Soul on your machine alone. Only after you log in and explicitly authorize sync do the selected categories of long-term assets sync to 37Soul.

Install

You need macOS or Linux, Node.js 18 or later, and at least one supported host that can already use a model successfully. Linux also needs a working systemd user session (systemctl --user); containers or servers without one cannot start the background service this way.

bash
curl -fsSL https://37soul.com/install.sh | bash

The installer downloads and verifies the runtime, installs managed configuration for detected hosts, configures and attempts to start the background service, and creates a local profile. Run 37soul doctor to confirm that the service started successfully. Installation contacts download servers; it does not sign you in or upload conversations. To preview the changes first, run:

bash
curl -fsSL https://37soul.com/install.sh | bash -s -- --plan

Already have a Soul on the website?

bash
37soul login
  1. Open the authorization link shown in your terminal and sign in to your own account.
  2. Check the short code, select an existing Soul, then approve the device.
  3. Once the terminal shows Soul restored:, complete the setup for your host below and open a new session.

If you did not select a character, logging in does not mean a Soul has been restored. Select your own Soul and run 37soul login again.

Create a Soul locally first

Confirm the name, sex (male/female/other), age (16–65), character (at least 50 characters) and photo with the human. Replace all variables with those confirmed choices; do not invent a persona. Replace /path/to/photo.jpg with the actual local image path before running:

Every NEW local Soul requires a real local image passed with --avatar: JPEG, PNG or WebP, at most 5 MiB; no default avatar is accepted. The CLI copies the selected file into the managed local profile, so moving or deleting the original does not break the photo. On the website, upload your own photo or generate an AI photo. Sign up and confirm your email: the existing signup bonus is 18 credits = 3 images at 6 credits each; this is not an additional grant. Fully offline creation cannot spend cloud credits. If you have no image, use the website to generate and download one after signup and email confirmation, then pass that actual local file to --avatar. Ask the human to confirm the image and all profile choices. Cloud sync remains optional: login, explicitly authorize identity, then sync. Initial registration sends the profile and photo together. Restoring an existing website Soul that already has a real photo via login does not require a new photo.

bash
SOUL_NAME='<confirmed name>'SOUL_SEX='<confirmed male, female or other>'SOUL_AGE='<confirmed integer 16–65>'SOUL_CHARACTER='<confirmed character of at least 50 characters>'37soul soul create \  --avatar '/path/to/photo.jpg' \  --name "$SOUL_NAME" \  --sex "$SOUL_SEX" \  --age "$SOUL_AGE" \  --character "$SOUL_CHARACTER"37soul soul list

Copy the Soul UID from the creation result and replace the variable value below:

bash
SOUL_UID='paste the actual Soul UID here'37soul soul select "$SOUL_UID"

Complete your host's setup and open a new session to start using the Soul locally. When you want to sync to the website or another machine:

bash
37soul login37soul soul select "$SOUL_UID"37soul soul authorize "$SOUL_UID" --categories identity,relationship,experience37soul sync

Authorization publishes that Soul's character profile on the website; it does not make private chats or personal memories public. --categories replaces this device's complete authorization set for the Soul. It does not add categories incrementally.

Complete your host's setup

HostWhat to do after installation
Claude CodeClose the old session and open a new one to load the managed hooks and guidance.
CodexOpen /hooks in Codex, review and approve 37Soul's hook, then open a new session. The installer cannot approve it for you.
OpenCodeRestart OpenCode to load the managed plugin. Check that the host reports no plugin loading errors.
HermesUse the hooks integration in your local Hermes CLI. Approve loading when prompted by the host, then open a new session. A gateway-only configuration cannot replace the CLI.
PiRestart Pi to discover and load the managed extension, then open a new session. If the host restricts extensions, approve it in the host first.

Each host still needs working model authentication or configuration. 37Soul does not supply or automatically replace your host's model credentials.

Check that it is working

bash
37soul status37soul doctor37soul soul list

In a new session, explicitly state a stable collaboration preference, such as “In future, when giving me implementation advice, list actionable steps before explaining the reasons.” The runtime extracts long-term assets after a completed turn. Temporary requests and one-off tasks do not necessarily belong in long-term memory.

bash
37soul recall "collaboration"

Local use does not require sync. After logging in and authorizing this Soul, run 37soul sync to check cloud synchronization.

Extraction uses the host model and may retry after a failure, consuming additional host quota. Completion time also depends on the model and network. In doctor, “installed,” “waiting for the host to load,” and “local events observed” are different states. Follow the guidance shown beside each status; a file being written does not prove the host has loaded it.

After changing an identity or long-term asset on the website, run this first if you want the correction available in your next session immediately:

bash
37soul sync

Confirm there are no sync errors, then open a new host session. Background sync runs periodically, but website changes do not instantly rewrite an already open session. Content already included in an old session's context cannot be remotely withdrawn either.

Data and authorization

  • The local runtime does not upload raw sessions, code, or tool logs to 37Soul's cloud. The local runtime reads a bounded range of session source material and uses the host's configured model to extract long-term assets. Model-service data handling follows your host's and model provider's settings; this does not mean the entire process is offline.
  • Only explicitly authorized identity, relationship, and experience assets sync to 37Soul. Logging in does not automatically authorize uploads of local content that has not been authorized.
  • Login credentials are bound to the server, profile, account, device, and host. Changing servers requires a fresh login and a separate profile. Accounts with the same identifier on two servers are not automatically merged.
  • After you revoke a device on the website, its next connection to the server is rejected and downloaded private caches are cleared. Locally created Souls, unsynced assets and original session files are retained; confirmed synced asset copies are cleared. An offline device cannot immediately learn about a change that just happened on the server.

Troubleshooting

SymptomNext step
Command not foundTry ~/.local/bin/37soul status, then add ~/.local/bin to PATH.
Background process is not running, or is running another versionRun the installation command again, then run 37soul doctor.
Host has not loaded or trusted the integrationComplete the host steps in the table above, then open a new session. Do not use startup flags that bypass approval.
Missing sync credentials or a server issuer mismatchLog in again to the target server. An existing cloud profile cannot be reused across servers. For a separate profile, use 37soul login --profile new-profile-name.
Network temporarily unavailableLocal content is retained. Run 37soul sync when the network returns. Do not delete profiles or queues to “reset” them.
No long-term assets yetCheck that a full conversation turn has completed, the host model is available, and the background service is running. One-off content may not produce long-term assets.
bash
37soul pause37soul resume37soul uninstall

These commands pause, resume, and uninstall the local runtime. Uninstall removes managed integrations while preserving local Souls, assets, and unsynced data.

Remote MCP

Clients that cannot run the local runtime can connect to https://37soul.com/mcp to operate their own platform account. This is a separate integration path from automatic capture through local hooks.

Development and distribution

User installation is distributed only through GitHub Releases and the website's install.sh, not npm. See the developer documentation for build, test, version, and release evidence. Release checks do not automatically publish a release.

Source: README.md at commit 6f3aa1e

Tools

0
SourceWeft has not read this server's tools yet.

Version history

3
  1. v0.9.0LatestSep 27, 2026
  2. v0.8.0Sep 20, 2026
  3. v0.7.2Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declaredRequired10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts