Kotlin Multiplatform SDK for the Mastodon API.

• Group: org.litote.mastodon.ktor.sdk
• License: Apache 2.0

• Ktor and kotlinx.serialization dependencies — fully KMP compatible
• Generate only the API operations you need from the published OpenAPI spec
• alpha stage SDK for operation composition (e.g. upload an image and post a media status)
• alpha stage Gradle plugin for usage with Gradle projects
• alpha stage CLI tools for command-line usage
• alpha stage MCP server to expose Mastodon tools to AI assistants (Claude Desktop, Claude Code, etc.)

See sdk/README.md.

The API reference (KDoc) documents the latest release; previous versions are available from the version selector.

The api artifact contains the generated clients and models of the operations used by the SDKs (statuses, media, home timeline, notifications, search), in the org.litote.mastodon.ktor.sdk.api package:

implementation("org.litote.mastodon.ktor.sdk:api:<version>")

val config = ClientConfiguration(
    baseUrl = "https://mastodon.example.com/",
    accessToken = accessToken,
)

val client = StatusesClient(config)
val response = client.createStatus(TextStatus(status = "Hello Mastodon!"))

The Mastodon OpenAPI spec maintained by this project is published as org.litote.mastodon.ktor.sdk:openapi. Use OpenAPI Ktor Client Generator to generate, in your own build, only the operations you use:

// build.gradle.kts
plugins {
    kotlin("multiplatform") // or kotlin("jvm")
    kotlin("plugin.serialization")
    id("org.litote.openapi.ktor.client.generator.gradle") version "<generator version>"
}

val mastodonSpec by configurations.creating

dependencies {
    mastodonSpec("org.litote.mastodon.ktor.sdk:openapi:<version>@json")
}

apiClientGenerator {
    generators {
        create("mastodon") {
            openApiFile = layout.file(provider { mastodonSpec.singleFile })
            // Use your own package: the SDK artifacts already contain org.litote.mastodon.ktor.sdk.api.
            basePackage = "com.example.mastodon"
            allowedPaths.set(
                setOf(
                    "/api/v1/accounts/{id}"
                ),
            )
        }
    }
}

The generated code needs kotlinx-serialization-json, kotlinx-coroutines-core, kotlin-logging and the Ktor client (core, cio, content-negotiation, serialization-kotlinx-json, logging). samples/custom-client is a working example.

Generated types are not interchangeable with the api artifact ones: use the SDKs or your own clients for a given operation, not both.

For operation composition (e.g. upload an image and post a media status).

See sdk/README.md for usage.

For projects that build with Gradle, the gradle-plugin module provides sendText and sendMedia tasks that call the SDK directly — no shell invocation needed.

See gradle-plugin/README.md for setup and usage.

Expose Mastodon tools to any MCP client (Claude Desktop, Claude Code, etc.) via a STDIO transport.

See mcp-server/README.md for setup and usage.

Command-line tools to post statuses to Mastodon.

See cli/README.md for usage.