AutoGineer
Generated banner for Kotlin MCP Server Generator
Generated logo for Kotlin MCP Server Generator

Kotlin MCP Server Generator

GitHubOfficialOriginally contributed by @troystaylor as prompts/kotlin-mcp-server-generator.prompt.md; moved into a skill by pull request #761Distributed by GitHub

  • Skill
  • Content generator
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Generate a complete Kotlin MCP server project with proper structure, dependencies, and implementation using the official io.modelcontextprotocol:kotlin-sdk library.
— the description by troystaylor

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured template and generation guide for building Model Context Protocol (MCP) servers in Kotlin. It includes the necessary Gradle configuration, project directory structure, and boilerplate code to implement MCP servers using the official Kotlin SDK. The generator emphasizes type safety, coroutine-based asynchronous operations, and structured logging, ensuring that developers can quickly scaffold a robust server with pre-configured tool registration, error handling, and testing utilities.

What it does

  • Generates a standard Gradle-based Kotlin project structure for MCP servers.
  • Configures essential dependencies including the official MCP SDK, Ktor, and kotlinx libraries.
  • Provides boilerplate code for server initialization and stdio transport setup.
  • Includes templates for tool registration with typed JSON schemas.
  • Sets up testing infrastructure using coroutine-based test utilities.
  • Generates a comprehensive README with installation, configuration, and usage instructions.

When to use it

  • When you need to bootstrap a new MCP server project in Kotlin.
  • When you want to ensure your MCP server follows standard Kotlin project conventions.
  • When you need a consistent starting point for implementing custom tools within an MCP architecture.
  • When you require a pre-configured environment that supports both stdio and SSE transports.

Advantages

  • Reduces boilerplate by providing a complete, ready-to-run project structure.
  • Ensures consistency across different MCP server implementations.
  • Promotes best practices like type safety and structured error handling.
  • Includes built-in support for testing and logging.

Usage examples

“Generate a new Kotlin MCP server project named 'WeatherService'.”
The agent provides the full directory structure, build.gradle.kts, and source files (Main.kt, Server.kt, etc.) pre-populated with the project name 'WeatherService'.
“Show me how to add a new tool to my generated Kotlin MCP server.”
The agent provides a template for a new tool file, demonstrating how to use buildJsonObject for the input schema and how to register it in the ToolRegistry.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/github/kotlin-mcp-server-generator/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip kotlin-mcp-server-generator.zip -d .agents/skills

Documentation by troystaylor

Kotlin MCP Server Project Generator

Generate a complete, production-ready Model Context Protocol (MCP) server project in Kotlin.

Project Requirements

You will create a Kotlin MCP server with:

  1. Project Structure: Gradle-based Kotlin project layout

  2. Dependencies: Official MCP SDK, Ktor, and kotlinx libraries

  3. Server Setup: Configured MCP server with transports

  4. Tools: At least 2-3 useful tools with typed inputs/outputs

  5. Error Handling: Proper exception handling and validation

  6. Documentation: README with setup and usage instructions

  7. Testing: Basic test structure with coroutines

Template Structure

myserver/
├── build.gradle.kts
├── settings.gradle.kts
├── gradle.properties
├── src/
│   ├── main/
│   │   └── kotlin/
│   │       └── com/example/myserver/
│   │           ├── Main.kt
│   │           ├── Server.kt
│   │           ├── config/
│   │           │   └── Config.kt
│   │           └── tools/
│   │               ├── Tool1.kt
│   │               └── Tool2.kt
│   └── test/
│       └── kotlin/
│           └── com/example/myserver/
│               └── ServerTest.kt
└── README.md

build.gradle.kts Template

plugins {
    kotlin("jvm") version "2.1.0"
    kotlin("plugin.serialization") version "2.1.0"
    application
}

group = "com.example"
version = "1.0.0"

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.modelcontextprotocol:kotlin-sdk:0.7.2")
    
    // Ktor for transports
    implementation("io.ktor:ktor-server-netty:3.0.0")
    implementation("io.ktor:ktor-client-cio:3.0.0")
    
    // Serialization
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
    
    // Coroutines
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
    
    // Logging
    implementation("io.github.oshai:kotlin-logging-jvm:7.0.0")
    implementation("ch.qos.logback:logback-classic:1.5.12")
    
    // Testing
    testImplementation(kotlin("test"))
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.9.0")
}

application {
    mainClass.set("com.example.myserver.MainKt")
}

tasks.test {
    useJUnitPlatform()
}

kotlin {
    jvmToolchain(17)
}

settings.gradle.kts Template

rootProject.name = "{{PROJECT_NAME}}"

Main.kt Template

package com.example.myserver

import io.modelcontextprotocol.kotlin.sdk.server.StdioServerTransport
import kotlinx.coroutines.runBlocking
import io.github.oshai.kotlinlogging.KotlinLogging

private val logger = KotlinLogging.logger {}

fun main() = runBlocking {
    logger.info { "Starting MCP server..." }
    
    val config = loadConfig()
    val server = createServer(config)
    
    // Use stdio transport
    val transport = StdioServerTransport()
    
    logger.info { "Server '${config.name}' v${config.version} ready" }
    server.connect(transport)
}

Server.kt Template

package com.example.myserver

import io.modelcontextprotocol.kotlin.sdk.server.Server
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
import io.modelcontextprotocol.kotlin.sdk.Implementation
import io.modelcontextprotocol.kotlin.sdk.ServerCapabilities
import com.example.myserver.tools.registerTools

fun createServer(config: Config): Server {
    val server = Server(
        serverInfo = Implementation(
            name = config.name,
            version = config.version
        ),
        options = ServerOptions(
            capabilities = ServerCapabilities(
                tools = ServerCapabilities.Tools(),
                resources = ServerCapabilities.Resources(
                    subscribe = true,
                    listChanged = true
                ),
                prompts = ServerCapabilities.Prompts(listChanged = true)
            )
        )
    ) {
        config.description
    }
    
    // Register all tools
    server.registerTools()
    
    return server
}

Config.kt Template

package com.example.myserver.config

import kotlinx.serialization.Serializable

@Serializable
data class Config(
    val name: String = "{{PROJECT_NAME}}",
    val version: String = "1.0.0",
    val description: String = "{{PROJECT_DESCRIPTION}}"
)

fun loadConfig(): Config {
    return Config(
        name = System.getenv("SERVER_NAME") ?: "{{PROJECT_NAME}}",
        version = System.getenv("VERSION") ?: "1.0.0",
        description = System.getenv("DESCRIPTION") ?: "{{PROJECT_DESCRIPTION}}"
    )
}

Tool1.kt Template

package com.example.myserver.tools

import io.modelcontextprotocol.kotlin.sdk.server.Server
import io.modelcontextprotocol.kotlin.sdk.CallToolRequest
import io.modelcontextprotocol.kotlin.sdk.CallToolResult
import io.modelcontextprotocol.kotlin.sdk.TextContent
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
import kotlinx.serialization.json.putJsonObject
import kotlinx.serialization.json.putJsonArray

fun Server.registerTool1() {
    addTool(
        name = "tool1",
        description = "Description of what tool1 does",
        inputSchema = buildJsonObject {
            put("type", "object")
            putJsonObject("properties") {
                putJsonObject("param1") {
                    put("type", "string")
                    put("description", "First parameter")
                }
                putJsonObject("param2") {
                    put("type", "integer")
                    put("description", "Optional second parameter")
                }
            }
            putJsonArray("required") {
                add("param1")
            }
        }
    ) { request: CallToolRequest ->
        // Extract and validate parameters
        val param1 = request.params.arguments["param1"] as? String
            ?: throw IllegalArgumentException("param1 is required")
        val param2 = (request.params.arguments["param2"] as? Number)?.toInt() ?: 0
        
        // Perform tool logic
        val result = performTool1Logic(param1, param2)
        
        CallToolResult(
            content = listOf(
                TextContent(text = result)
            )
        )
    }
}

private fun performTool1Logic(param1: String, param2: Int): String {
    // Implement tool logic here
    return "Processed: $param1 with value $param2"
}

tools/ToolRegistry.kt Template

package com.example.myserver.tools

import io.modelcontextprotocol.kotlin.sdk.server.Server

fun Server.registerTools() {
    registerTool1()
    registerTool2()
    // Register additional tools here
}

ServerTest.kt Template

package com.example.myserver

import kotlinx.coroutines.test.runTest
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse

class ServerTest {
    
    @Test
    fun `test server creation`() = runTest {
        val config = Config(
            name = "test-server",
            version = "1.0.0",
            description = "Test server"
        )
        
        val server = createServer(config)
        
        assertEquals("test-server", server.serverInfo.name)
        assertEquals("1.0.0", server.serverInfo.version)
    }
    
    @Test
    fun `test tool1 execution`() = runTest {
        val config = Config()
        val server = createServer(config)
        
        // Test tool execution
        // Note: You'll need to implement proper testing utilities
        // for calling tools in the server
    }
}

README.md Template

# {{PROJECT_NAME}}

A Model Context Protocol (MCP) server built with Kotlin.

## Description

{{PROJECT_DESCRIPTION}}

## Requirements

- Java 17 or higher
- Kotlin 2.1.0

## Installation

Build the project:

\`\`\`bash
./gradlew build
\`\`\`

## Usage

Run the server with stdio transport:

\`\`\`bash
./gradlew run
\`\`\`

Or build and run the jar:

\`\`\`bash
./gradlew installDist
./build/install/{{PROJECT_NAME}}/bin/{{PROJECT_NAME}}
\`\`\`

## Configuration

Configure via environment variables:

- `SERVER_NAME`: Server name (default: "{{PROJECT_NAME}}")
- `VERSION`: Server version (default: "1.0.0")
- `DESCRIPTION`: Server description

## Available Tools

### tool1
{{TOOL1_DESCRIPTION}}

**Input:**
- `param1` (string, required): First parameter
- `param2` (integer, optional): Second parameter

**Output:**
- Text result of the operation

## Development

Run tests:

\`\`\`bash
./gradlew test
\`\`\`

Build:

\`\`\`bash
./gradlew build
\`\`\`

Run with auto-reload (development):

\`\`\`bash
./gradlew run --continuous
\`\`\`

## Multiplatform

This project uses Kotlin Multiplatform and can target JVM, Wasm, and iOS.
See `build.gradle.kts` for platform configuration.

## License

MIT

Generation Instructions

When generating a Kotlin MCP server:

  1. Gradle Setup: Create proper build.gradle.kts with all dependencies

  2. Package Structure: Follow Kotlin package conventions

  3. Type Safety: Use data classes and kotlinx.serialization

  4. Coroutines: All operations should be suspending functions

  5. Error Handling: Use Kotlin exceptions and validation

  6. JSON Schemas: Use buildJsonObject for tool schemas

  7. Testing: Include coroutine test utilities

  8. Logging: Use kotlin-logging for structured logging

  9. Configuration: Use data classes and environment variables

  10. Documentation: KDoc comments for public APIs

Best Practices

  • Use suspending functions for all async operations

  • Leverage Kotlin's null safety and type system

  • Use data classes for structured data

  • Apply kotlinx.serialization for JSON handling

  • Use sealed classes for result types

  • Implement proper error handling with Result/Either patterns

  • Write tests using kotlinx-coroutines-test

  • Use dependency injection for testability

  • Follow Kotlin coding conventions

  • Use meaningful names and KDoc comments

Transport Options

Stdio Transport
val transport = StdioServerTransport()
server.connect(transport)
SSE Transport (Ktor)
embeddedServer(Netty, port = 8080) {
    mcp {
        Server(/*...*/) { "Description" }
    }
}.start(wait = true)

Multiplatform Configuration

For multiplatform projects, add to build.gradle.kts:

kotlin {
    jvm()
    js(IR) { nodejs() }
    wasmJs()
    
    sourceSets {
        commonMain.dependencies {
            implementation("io.modelcontextprotocol:kotlin-sdk:0.7.2")
        }
    }
}

Files

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Originally contributed by
GitHub avatar of troystaylor@troystayloras prompts/kotlin-mcp-server-generator.prompt.mdmoved into a skill by pull request #761
Publisher
GitHub (Official)
Distributed by
GitHub
Source
github/awesome-copilot · skills/kotlin-mcp-server-generator · commit 797337f
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
troystaylor

AutoGineer is not affiliated with or endorsed by troystaylor or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download kotlin-mcp-server-generator.zip