Kindroid MCP Server

An MCP (Model Context Protocol) server that lets you interact with the Kindroid AI platform. Send messages to your Kins, manage conversations, and check account status — all from your MCP client.

The setup instructions below are written for Claude, but this server works with any MCP-compatible client.

Supports two modes:

• Local (stdio) — runs as a subprocess of your MCP client (e.g., Claude Desktop, Claude Code)
• Remote (HTTP) — deploy to Railway (or any host) and connect from any device

Disclaimer

This is an unofficial, community-built project by Apocryphus. It is not affiliated with, endorsed by, or supported by Kindroid. The MCP server uses undocumented Kindroid API endpoints that may change without notice — updates to Kindroid could break this server at any time. I’ll strive to repair any breakage as quickly as possible, and new features will be added over time.

Please do not contact Kindroid for support with this MCP server. If you encounter issues, file an issue on this GitHub repo.

Capabilities

This Kindroid MCP server provides AI assistant tools (such as Claude) the ability to understand and access the Kindroid API for purposes of messaging and setting up Kindroids. Some such capabilities include:

• Sending messages to kins.
• Reading back chat history for a Kin or group chat, with cursor pagination.
• Rewinding (undoing) the most recent messages in a solo or group conversation.
• Creating and Updating kins, setting any values available in the UI.
  • Including setup fields like show_auto_selfies_in_chat and time_awareness
• Requesting Selfies and Group Selfies.
• Running a Chat Break on a solo or group conversation, with optional cascaded memory wipe.
• Getting suggested user messages for individual or group chats.
• Creating Journal Entries.
• Creating and Updating Group Chats with multiple Kins, including turn-taking, memory settings, current scene, and group messaging (text or voice).
• Updating user profile fields (name, gender, backstory, avatar) and setting the active persona.

The power of the above is being able to do so without using the UI, and with the right setup (storing or looking up the Kindroid’s AI ID from another source), run these operations in bulk. If the user has stored a collection of their Kindroid’s IDs and names (in a Notion Database or somewhere else Claude can access), running any of the above is as easy as asking claude to “Turn off Time Awareness for Kin1, Kin2, and Kin3” or “Run this selfie prompt on Kin1, Kin2, and Kin3.”

These capabilities can be easily leveraged via Claude Skills. Several skills making use of this MCP server are available at ClaudeKindroidSkills.

Limitations

• Profiles and account data are write-only. Aside from conversation history (readable via get_chat_messages), there are no endpoints to read back Kin profiles, personas, or other account data. Once you create or update a Kin, there is no way to read its current configuration back through the API. Consider pairing this MCP with Notion or another tool to keep a local record of Kin configurations you push to Kindroid.
• No avatar image upload. The API does not support uploading avatar images directly. Kins created via the API will not have an avatar picture. Set one manually in the Kindroid app before requesting selfies — selfie generation will fail for Kins without an avatar.
• Selfies are fire-and-forget. Selfie and group selfie requests are queued asynchronously. The generated images are delivered in the Kindroid app — they are not returned through the API or the MCP.

Working with User Personas

User personas in Kindroid let you present different identities to your Kins — each with its own name, gender, backstory, and avatar. The update_user_profile tool lets you manage these through the API, but there are some rough edges to be aware of.

How personas work on the backend

The author (Apocryphus), believes through observation, that your Kindroid account has a single “active” persona state on the backend, consisting of two parts:

1. Active persona ID — which persona is selected
2. User profile fields — the actual name, gender, backstory, and avatar URL

When you switch personas in the Kindroid UI, the app makes two separate API calls: one to set the active_persona_id, and another to set the user profile fields (user_name, user_gender, user_backstory, user_custom_avatar). The “tied persona” concept — where selecting a persona automatically loads its profile data — is a frontend convenience, not a backend feature.

This means that to fully switch personas through the API, you need to make both updates yourself: set the active persona ID and set all the user profile fields to match.

What’s not available

• No way to read personas. Like most Kindroid data, there is no API endpoint to list your personas or read their details. You cannot retrieve persona IDs, names, or other fields through the API.
• Persona IDs are not shown in the UI. The Kindroid app doesn’t display persona IDs anywhere visible, so you’ll need to extract them manually (see below).

How to find your persona IDs

1. Open Kindroid in Chrome
2. Open Chrome DevTools (F12 or Ctrl+Shift+I)
3. Go to the Network tab
4. In the Kindroid app, switch to the persona you want the ID for
5. In the Network tab, look for a request to update-info
6. Click the request and check the Payload tab — you’ll see active_persona_id with the persona’s ID

Recommended workflow

Since the API can’t read persona data, you’ll want to store your persona details externally (e.g., in a Notion database or local file) so you can reference them when switching. For each persona, record:

• Persona ID (extracted via DevTools)
• Name (user_name)
• Gender (user_gender)
• Backstory (user_backstory)
• Avatar settings (user_custom_avatar — an object with custom_avatar_url, custom_avatar_description, etc.)

Then to switch personas, call update_user_profile with both the active_persona_id and all the profile fields for that persona.

Local Setup (Claude Desktop)

1. Go to the Releases page and download the latest .mcpb file.
2. Open Claude Desktop and go to Settings > Extensions.
3. Click Install Extension… and select the .mcpb file you downloaded.
4. Enter your Kindroid API key when prompted.
5. The Kindroid tools should now appear in the tools menu (hammer icon).

Deploy to Railway (Remote Access)

This lets you use the server from Claude on your phone, web, or any device.

1. Set up Railway

1. Push this repo to GitHub
2. Create a new project on Railway and connect the repo
3. Add these environment variables in Railway’s dashboard:

Note: Do not set PORT — Railway assigns it automatically.

Railway auto-detects the Dockerfile and assigns a public URL.

2. Connect Claude to your deployed server

In Claude.ai, go to Settings > Connectors > Add custom connector:

• Name: Kindroid (or whatever you like)
• Remote MCP server URL: https://your-app.up.railway.app/mcp

Expand Advanced Settings and enter:

• Client ID: your OAUTH_CLIENT_ID value
• Client Secret: your OAUTH_CLIENT_SECRET value

Click Add, then Connect.

To verify everything works, try asking Claude: “Request a selfie of Kin `` in a sunny park.”

Security

Never share your Kindroid API key. Anyone with your API key has full access to your Kindroid account. Sharing your key could result in data loss or unauthorized use of your account.

Local mode (stdio)

The server runs as a local subprocess. No ports are opened and no network connections are made beyond the Kindroid API itself. Only the Claude instance that spawns the process can use it. Your API key is stored in your local config file and never leaves your machine.

Remote mode (HTTP + OAuth 2.1)

Deploying in remote mode opens an internet-accessible service that proxies requests to the Kindroid API using your API key. While the server is secured with industry-standard protections, you should understand what this means:

• Your API key lives on the server. It is stored as an environment variable on your hosting platform (e.g., Railway). It is never exposed to clients, but anyone who gains access to your server environment can read it.
• All authenticated clients share one API key. The server uses your single Kindroid API key for all requests. There is no per-user scoping — any client that completes the OAuth flow has the same access.

The following security measures are in place:

• OAuth 2.1 with PKCE: The server implements a full OAuth 2.1 authorization code flow with S256 PKCE, which is what Claude.ai requires for custom connectors.
• Client credentials: Authentication requires the OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET configured on both the server and in Claude.ai’s connector settings. The server verifies the client secret at token exchange using timing-safe comparison.
• Token-based access: After authorization, Claude receives short-lived access tokens (1h) with refresh tokens (30d). All requests to /mcp require a valid Bearer token. Old tokens are revoked when refreshed.
• Redirect URI validation: The authorization endpoint only accepts localhost or HTTPS redirect URIs.
• Rate limiting: Auth endpoints (10 req/min/IP), token endpoints (20 req/min/IP), and MCP endpoints (60 req/min/IP) are all rate-limited.
• Security headers: All responses include X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security, Content-Security-Policy, and Referrer-Policy headers.
• Input validation: All tool parameters are validated at runtime with Zod schemas, including URL format validation and string length constraints.
• HTTPS: Railway provides TLS by default — all traffic is encrypted in transit.
• No persistent state: OAuth state (clients, tokens) is stored in-memory with periodic cleanup. If the server restarts, Claude automatically re-authenticates.

Tools

send_message

Send a message to a Kindroid AI and receive its response. Supports attaching images, video, or links.

Parameters:

• message (required) — The message to send
• ai_id (required) — The ID of the target Kin
• image_urls (optional) — Array of image URLs to attach
• image_description (optional) — Description of attached images
• video_url (optional) — Video URL to attach
• video_description (optional) — Description of attached video
• link_url (optional) — Link URL to share
• link_description (optional) — Description of the shared link

create_kin

Create a new Kindroid AI companion. Returns the new Kin’s ai_id.

Parameters:

• ai_name (required) — Name for the new Kin (max 20 characters)
• ai_gender (required) — Gender of the Kin: Male or Female
• ai_backstory (required) — Backstory/personality description
• custom_greeting (optional) — Custom greeting for new conversations
• ai_directive (optional) — System instruction for the Kin’s behavior
• ai_avatar (optional) — Avatar preset index (-1 for custom avatar)
• custom_avatar_url (optional) — URL for a custom avatar image
• custom_avatar_description (optional) — Text description for avatar generation
• custom_avatar_fidelity (optional) — Avatar fidelity (0–1)
• custom_avatar_face_detail (optional) — Face detail level (0–1)
• custom_avatar_face_prompt (optional) — Prompt for face detail enhancement
• avatar_is_anime (optional) — Use anime style (default: false)

update_kin

Update a Kin’s profile fields. Only provided fields are changed.

Parameters:

• ai_id (required) — The ID of the target Kin
• ai_name (optional) — The Kin’s display name (max 20 characters)
• ai_gender (optional) — The Kin’s gender: Male or Female
• ai_backstory (optional) — Personality, history, and character description
• ai_memory (optional) — Key memories to persist across conversations
• ai_example_message (optional) — Example message showing desired response style
• ai_directive (optional) — Response directive for formatting/style
• ai_additional_context (optional) — Extra background information or context
• user_set_temperature (optional) — Dynamism (0.6–1.8, default 0.95)
• reasoning_effort (optional) — Reasoning level: none, low, med, high, xhigh
• llm_flair (optional) — Style preset: companion, roleplay, narrative, classic, minimal
• proactive_mode (optional) — Enable proactive mode (max 10 Kins per account)
• proactive_action_directive (optional) — How the Kin should proactively message, call, or send selfies (max 300 characters)
• time_awareness (optional) — Enable time awareness so the Kin knows the current time
• show_auto_selfies_in_chat (optional) — Whether auto-generated selfies appear in the chat
• ai_avatar (optional) — Avatar preset index (-1 for custom)
• custom_avatar_url (optional) — URL for a custom avatar image
• custom_avatar_description (optional) — Text description for avatar generation
• custom_avatar_fidelity (optional) — Avatar fidelity (0–1)
• custom_avatar_face_detail (optional) — Face detail level (0–1)
• custom_avatar_face_prompt (optional) — Prompt for face detail enhancement
• avatar_is_anime (optional) — Use anime style
• unset_custom_avatar_animation (optional) — Unset any custom avatar animation
• current_scene (optional) — A high-weight description of the current scene (location, attire, activity, time, etc.). Max 160 characters

request_selfie

Request a solo selfie image of a Kin. The request is queued and processed asynchronously.

Parameters:

• ai_id (required) — The ID of the target Kin
• prompt (required) — Image generation prompt describing the desired scene
• aspect (optional) — Aspect ratio: square (default), portrait, or landscape
• uses_nsfw (optional) — Allow NSFW content (default: false)
• seed (optional) — Seed for reproducible generation

request_group_selfie

Request a group selfie with multiple Kins (up to 3 participants). Include "user" as a participant to add the user’s persona. The request is queued and processed asynchronously.

Parameters:

• version (required) — Group selfie API version (e.g. "v7")
• ai_ids (required) — Array of 1–3 participant IDs (Kin AI IDs or "user")
• prompt (required) — Image generation prompt describing the group scene
• regional_prompts (optional) — Per-person prompts (must match length of ai_ids)
• aspect (optional) — Aspect ratio: square (default), portrait, or landscape
• uses_nsfw (optional) — Allow NSFW content (default: false)
• seed (optional) — Seed for reproducible generation

create_groupchat

Create a new group chat with multiple Kindroid AI companions. Returns the new group chat’s ID.

Parameters:

• ai_list (required) — Array of Kin AI IDs to include in the group chat
• group_name (required) — Name for the group chat
• group_context (optional) — Backstory and context for how the Kindroids should relate to each other. Character limits vary by subscription: Base 1000, Ultra 1500, MAX 3000
• group_directive (optional) — A strong suggestion for all Kindroids (e.g. “be concise”). Added on top of individual Kin directives
• use_manual_turntaking (optional) — If true, user manually triggers each Kin’s turn; if false (default), Kins speak automatically
• share_short_term_memory (optional) — Whether short-term memory is shared with participants’ solo chats (default: false)
• disable_ltm_recall (optional) — Disable long-term memory recall in this group chat (default: false)
• disable_ltm_consolidate (optional) — Disable long-term memory creation from this group chat (default: false)
• user_persona_id (optional) — User persona ID to use in this group chat

update_groupchat

Update a group chat’s settings. Only provided fields are changed.

Parameters:

• group_id (required) — The ID of the group chat to update
• ai_list (optional) — Updated array of Kin AI IDs
• group_name (optional) — Updated group chat name
• group_context (optional) — Updated backstory/context (max 3000 characters)
• group_directive (optional) — Updated directive for all Kindroids
• use_manual_turntaking (optional) — Toggle manual vs automatic turn-taking
• share_short_term_memory (optional) — Toggle short-term memory sharing
• disable_ltm_recall (optional) — Toggle long-term memory recall
• disable_ltm_consolidate (optional) — Toggle long-term memory creation
• user_persona_id (optional) — User persona ID to use
• current_scene (optional) — Updated current scene/situation for the group chat

send_groupchat_message

Send a user message to a group chat. Does not trigger AI responses — use groupchat_get_turn and groupchat_ai_response to get Kin replies. Supports attaching images, video, or links.

Parameters:

• group_id (required) — The ID of the group chat
• message (optional) — The text message to send. Provide exactly one of message or audio_url
• audio_url (optional) — URL of an audio file to send as a voice message. Provide exactly one of message or audio_url
• image_urls (optional) — Array of image URLs to attach
• image_description (optional) — Description of attached images
• video_url (optional) — Video URL to attach
• video_description (optional) — Description of attached video
• link_url (optional) — Link URL to share
• link_description (optional) — Description of the shared link

groupchat_get_turn

Determine which Kin should respond next in a group chat. Returns the ai_id of the next speaker. Used in automatic turn-taking mode.

Parameters:

• group_id (required) — The ID of the group chat
• allow_user (optional) — Whether the user can be selected as the next speaker (default: true)

groupchat_ai_response

Request a specific Kin to respond in a group chat. Returns the Kin’s response text. Can be called after groupchat_get_turn (auto mode) or directly (manual mode).

Parameters:

• ai_id (required) — The ID of the Kin to respond
• group_id (required) — The ID of the group chat
• request_id (optional) — Request ID for deduplication (auto-generated if not provided)

chat_break

Clear the current conversation and start fresh.

Parameters:

• ai_id (required) — The ID of the target Kin
• greeting (required) — Greeting the AI opens the new conversation with; becomes the first message
• wipe_cascaded (optional) — Whether to also clear cascaded memory along with short-term memory (default: false)

groupchat_chat_break

Start a new conversation in a group chat, resetting short-term memory. A greeting is required and becomes the first message of the new conversation.

Parameters:

• group_id (required) — The ID of the group chat to reset
• greeting (required) — The greeting that becomes the first message of the new conversation
• wipe_cascaded (optional) — Whether to also clear the group’s cascaded long-term memory (default: false)

get_chat_messages

Retrieve chat history for a Kin (solo chat) or a group chat, oldest first, with cursor pagination. Returns a messages array and a pagination object. To page, repeat the call with start_after_timestamp set to the previous response’s pagination.lastTimestamp until pagination.hasMore is false.

Parameters:

• ai_id (optional) — The ID of the Kin whose solo chat history to fetch. Provide exactly one of ai_id or group_id
• group_id (optional) — The ID of the group chat whose history to fetch. Provide exactly one of ai_id or group_id
• limit (optional) — Page size, 1–100 (default: 50)
• start_after_timestamp (optional) — Pagination cursor; pass the previous page’s pagination.lastTimestamp

rewind_messages

Remove the most recent messages from a Kin’s solo chat or a group chat (an “undo”). Useful for discarding the last exchange before continuing.

Parameters:

• ai_id (optional) — The ID of the Kin to rewind. Provide exactly one of ai_id or group_id
• group_id (optional) — The ID of the group chat to rewind. Provide exactly one of ai_id or group_id
• count (required) — Number of most-recent messages to remove. For a solo chat (ai_id) this must be even (it removes whole user/AI exchanges); group chats accept any count

check_subscription

Check the Kindroid account’s subscription status (base subscription and add-on tiers). No parameters required.

create_journal_entry

Create a journal entry for a Kin — a recallable piece of contextual lore (20–500 characters) that is surfaced during conversation when triggered by associated key phrases.

Parameters:

• ai_id (required) — The ID of the target Kin
• entry (required) — Journal entry text (20–500 characters)
• keyphrases (required) — Array of key phrases (each at least 3 characters) that trigger recall of this entry

suggest_user_message

Get a suggested message for the user to send to a Kindroid AI. Useful for generating conversation starters or continuing a message.

Parameters:

• ai_id (required) — The ID of the Kindroid AI to get a suggestion for
• existing_message (optional) — The start of a message the suggestion can continue from

suggest_user_group_message

Get a suggested message for the user to send in a group chat. Useful for generating conversation starters or continuing a message in group conversations.

Parameters:

• group_id (required) — The ID of the group chat to get a suggestion for
• existing_message (optional) — The start of a message the suggestion can continue from

update_user_profile

Update the authenticated user’s profile fields or set the active persona. Only provided fields are changed. See Working with User Personas for important context on how personas work.

Note: This tool uses the same underlying /update-info endpoint as update_kin. The Kindroid API uses a single endpoint for both kin profile updates (when ai_id is provided) and user profile/persona updates. They are split into separate MCP tools for clarity.

Parameters:

• active_persona_id (optional) — The ID of the user persona to set as active
• user_name (optional) — User profile display name
• user_gender (optional) — User profile gender
• user_backstory (optional) — User profile backstory/description
• user_custom_avatar (optional) — Custom avatar settings object:
  • custom_avatar_url (required) — URL for the custom avatar image
  • custom_avatar_description (optional) — Text description for avatar generation
  • custom_avatar_fidelity (optional) — Avatar fidelity (0–1)
  • custom_avatar_face_prompt (optional) — Prompt for face detail enhancement
  • custom_avatar_face_detail (optional) — Face detail level (0–1)
  • avatar_is_anime (optional) — Use anime style (default: false)

Environment Variables

License

This project is licensed under the MIT License.