kotlin-lib-mcp

Give your AI agent the real sources of any Maven-published Kotlin/Java library.

An MCP server that, on request, downloads the sources of a
library (e.g. io.ktor:ktor-client-core:3.5.1), parses them with the Kotlin Analysis API
(standalone K2/FIR mode), and exposes structured information — public API surface, KDoc,
dependencies/metadata, raw source + search — to MCP clients such as Claude Code and Claude
Desktop. An optional Compose Desktop dashboard runs the same server in-process.

Why this and not a docs-lookup server?

Most documentation MCP servers scrape rendered doc sites or feed the model pre-digested
summaries. This one works from the published sources jar — the ground truth:

• Resolved signatures, not regex guesses. Declarations are analyzed with the same
  Analysis API that powers the Kotlin IDE, so get_api_signature returns real, type-resolved
  signatures (with graceful best-effort fallback when transitive dependencies are missing).
• KMP-aware. Kotlin Multiplatform libraries publish per-target sources jars; these are
  resolved properly via .module Gradle metadata, and every symbol is tagged with its targets.
• KDoc as data. Summaries, descriptions and tags are extracted per declaration — not
  whole HTML pages.
• Exact version you asked for, offline after the first fetch. Everything is cached on
  disk keyed by group/artifact/version; no re-downloads, no drift between the docs and the
  version you actually depend on.
• Raw source when you need it. get_source and bounded search_source let the agent
  read the actual implementation, not just the API.

Quick start (no build required)

Option 1 — release zip. Download the latest
release, unzip (needs a
Java 21+ runtime), then:

claude mcp add kotlin-lib -- /path/to/kotlin-lib-mcp-server-<version>/bin/server --transport stdio

Option 2 — Docker.

claude mcp add kotlin-lib -- docker run -i --rm -v kotlin-lib-mcp-cache:/home/mcp/.cache ghcr.io/aoreshkov/kotlin-lib-mcp

Option 3 — MCP Registry. The server is published to the
official MCP registry as
io.github.aoreshkov/kotlin-lib-mcp; registry-aware clients can install it from there.

Or in .mcp.json / Claude Desktop config:

{
  "mcpServers": {
    "kotlin-lib": {
      "command": "C:/path/to/kotlin-lib-mcp-server-<version>/bin/server.bat",
      "args": ["--transport", "stdio"]
    }
  }
}

For remote use, run the http transport (--transport http --port 3000) and point the client
at http://127.0.0.1:3000/mcp — DNS-rebinding protection admits localhost hosts by default;
--allowed-host/--allowed-origin extend the allowlist for non-localhost deployments.

CLI flags: --transport stdio|http, --port <int> (default 3000), --allowed-host <host> /
--allowed-origin <url> (repeatable; extend the http transport's localhost-only defaults),
--cache-dir <path>, --repo <url> (repeatable; Maven Central is the default), --help.

Tools

All tools take a Maven coordinate (group:artifact:version). Call fetch_library first —
it downloads, extracts and analyzes the sources once; every other tool answers from the cached
index. fetch_library, list_versions and get_latest_version also accept group:artifact, and
fetch_library accepts group:artifact:latest to resolve the latest stable release.

Every tool ships the metadata the MCP spec encourages clients to use: a display title,
behavior annotations (readOnlyHint: true everywhere except fetch_library, which is
additive-only — destructiveHint: false, idempotentHint: true; tools that reach Maven
repositories set openWorldHint: true, cache-only tools false), and a typed outputSchema
derived from the response DTO's serializer. Results carry both pretty-printed JSON text and the
matching structuredContent object, so structured-output clients and plain-text clients see the
same payload.

fetch_library also reports progress notifications (download → analyze → cache) when the
client sends a progressToken, and the server advertises the logging capability — its logs
mirror to clients as notifications/message (respecting logging/setLevel), which matters on
stdio where stderr is often dropped.

Resources: each cached library is readable at
kotlinlib://{group}/{artifact}/{version}/index (the parsed index as JSON); the list updates as
libraries are fetched, and the same URI shape is published as a resource template, so any
cached coordinate is directly addressable. Prompt: explain_public_api(coordinate, package?)
renders an explanation request grounded in the cached signatures and KDoc.

Building from source

./gradlew build                                    # build everything
./gradlew test                                     # unit tests
./gradlew :server:run --args="--transport stdio"   # local MCP over stdio (default)
./gradlew :server:run --args="--transport http --port 3000"   # Streamable HTTP at /mcp
./gradlew :dashboard:run                           # Compose Desktop UI
./gradlew :server:installDist                      # standalone launcher in server/build/install/server/bin

Requires JDK 21 (resolved automatically via Gradle toolchains).

Cache

Downloads and the parsed index live under the OS cache dir + kotlin-lib-mcp
(%LOCALAPPDATA%\kotlin-lib-mcp on Windows, ~/Library/Caches/kotlin-lib-mcp on macOS,
$XDG_CACHE_HOME/kotlin-lib-mcp elsewhere), keyed by group/artifact/version — browsable and
safe to delete. --cache-dir overrides it.

Notes

• stdio rule: stdout carries only MCP protocol frames; all logging goes to stderr
  (Kermit → SLF4J → Logback, logback.xml).
• Kotlin and the Analysis API artifacts are version-locked in gradle/libs.versions.toml —
  bump them together. Symbols whose types can't be resolved (missing transitive deps) degrade
  to bestEffort: true PSI signatures instead of failing.

Contributing

Contributions welcome — see CONTRIBUTING.md. Release history lives in
CHANGELOG.md; security reports go through
private vulnerability reporting.

Support

If kotlin-lib-mcp saves you time, consider
sponsoring its maintenance. Sponsorship funds
keeping the Analysis API version-lock current with new Kotlin releases and the
supply-chain-hardened release pipeline. Every tier is appreciated.

License

Apache-2.0