Space MCP Server

Kotlin MCP server for JetBrains Space code reviews and merge requests.

Requirements

• Java 21
• Access to a JetBrains Space instance such as https://jetbrains.team
• A Space access token for the recommended env-based local auth flow, or a Space OAuth application for space_authorize

What It Supports

• OAuth authorization code flow with PKCE against https://jetbrains.team
• Stored credentials with refresh-token support
• Listing visible Space projects
• Listing project reviews with public HTTP API filters:
  • repository
  • state
  • type
  • text
  • author
  • reviewer
  • from
  • to
• Aggregating "my reviews" across visible projects by scanning projects with author=me and reviewer=me
• Fetching a review with:
  • resolved review author / creator details when available
  • branch information
  • commits
  • optionally changed files
  • review feed messages
  • flattened human-authored comments
  • code discussion threads and replies
• Listing changed files in a review or merge request with normalized:
  • repository
  • path / old path
  • revision
  • diff size
  • conflict / read metadata when available
• Listing human-authored review comments with optional author filtering
• Posting a plain review comment to the main review feed
• Creating a code discussion anchored to a file/line
• Replying to an existing discussion channel

Quick Start

1. Get the runnable fat jar in one of these ways:

   • Download it from GitHub Releases.

   • Or build it from source:

     ./gradlew build

     build includes tests and ktlint checks.

   In both cases, the file you want is the fat jar:

   build/libs/space-mcp-server-0.2.0-all.jar
   

2. Configure your MCP host to run that jar with java -jar:

   {
     "mcpServers": {
       "Space": {
         "command": "java",
         "args": [
           "-jar",
           "/path/to/space-mcp-server/build/libs/space-mcp-server-0.2.0-all.jar"
         ],
         "env": {
           "SPACE_SERVER_URL": "https://jetbrains.team",
           "SPACE_ACCESS_TOKEN": "your-token"
         }
       }
     }
   }

   If java is not Java 21 on your machine, use the absolute path to a Java 21 binary instead.

3. Authenticate:

   • Recommended: set SPACE_SERVER_URL and SPACE_ACCESS_TOKEN in the MCP host config for local non-interactive auth.
   • Alternative: call space_authorize once to complete OAuth.

4. Verify the integration with:

   • space_auth_status
   • space_list_my_reviews
   • space_get_review
   • space_list_review_changes
   • space_list_review_comments

Build

./gradlew build

The runnable fat jar is created at:

build/libs/space-mcp-server-0.2.0-all.jar

GitHub Workflows

• CI runs on every pull request and on pushes to master and main.
• The CI job runs ./gradlew build, which includes compilation, tests, and ktlint checks.
• Every CI run uploads:
  • the runnable fat jar artifact
  • Gradle reports and test results
• Release runs on pushed tags matching v* and can also be started manually with a tag input from the Actions UI.
• Release runs build the server, publish a versioned fat jar plus SHA256SUMS.txt as workflow artifacts, and attach those files to the GitHub release.

Run

If you downloaded the release jar, run that file. If you built from source, run the jar from build/libs.

java -jar build/libs/space-mcp-server-0.2.0-all.jar

The server uses stdio transport.

Authorization

The server supports two auth modes:

• direct bearer-token bootstrap via environment variables for local stdio clients
• OAuth via the space_authorize MCP tool

Environment Variables (Recommended)

This is the default and recommended authorization flow for local MCP clients.

Set these environment variables in the MCP host configuration:

• SPACE_ACCESS_TOKEN
• SPACE_SERVER_URL for your Space organization URL, for example https://jetbrains.team
• optional SPACE_SCOPE
• optional SPACE_CLIENT_ID

SPACE_ACCESS_TOKEN also overrides the stored access token at runtime when OAuth credentials already exist.

Example local MCP config:

{
  "mcpServers": {
    "Space": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/space-mcp-server/build/libs/space-mcp-server-0.2.0-all.jar"
      ],
      "env": {
        "SPACE_SERVER_URL": "https://jetbrains.team",
        "SPACE_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

When you use OAuth, stored credentials are written to:

• $XDG_CONFIG_HOME/space-mcp-server/credentials.json, or
• ~/.config/space-mcp-server/credentials.json

OAuth

OAuth is available as a secondary flow when you do not want to pass a Space access token directly through the MCP host configuration.

Use the space_authorize MCP tool with:

• clientId
• optional clientSecret
• optional serverUrl (defaults to https://jetbrains.team)
• optional scope (defaults to **)
• optional redirectUri

Default redirect URI:

http://localhost:63363/api/space/oauth/authorization_code

For a normal Space application, configure the exact same redirect URI in the Space app settings.

Common Tool Flow

Check the current auth state:

{ "name": "space_auth_status", "arguments": {} }

Example response:

{
  "configured": true,
  "authenticated": true,
  "serverUrl": "https://jetbrains.team",
  "currentUser": {
    "id": "hero-001",
    "username": "Leia.Organa"
  }
}

List your reviews:

{
  "name": "space_list_my_reviews",
  "arguments": {
    "projectKey": "ALDERAAN",
    "role": "both",
    "limit": 20
  }
}

Example response:

{
  "reviews": [
    {
      "projectKey": "ALDERAAN",
      "matchedRoles": ["reviewer"],
      "review": {
        "number": 1138,
        "title": "[falcon] Tune hyperdrive ignition timing",
        "resolvedAuthor": {
          "username": "Han.Solo"
        }
      }
    }
  ],
  "scannedProjects": 20,
  "projectScanTruncated": true,
  "requestedLimit": 20
}

Fetch a review with commits and comments:

{
  "name": "space_get_review",
  "arguments": {
    "projectKey": "ALDERAAN",
    "review": "number:1138",
    "includeCommits": true,
    "includeChanges": true,
    "includeComments": true
  }
}

Example response excerpt:

{
  "review": {
    "number": 1138,
    "title": "[falcon] Tune hyperdrive ignition timing",
    "resolvedAuthor": {
      "username": "Han.Solo"
    }
  },
  "commits": [
    {
      "repositoryInReview": {
        "name": "millennium-falcon"
      },
      "commits": [
        {
          "id": "cafebabedeadbeef00112233445566778899aabb",
          "author": {
            "name": "Han Solo"
          }
        }
      ]
    }
  ],
  "changes": {
    "scope": "merge-request-files",
    "changes": [
      {
        "repository": "millennium-falcon",
        "path": "src/Hyperdrive.kt",
        "changeType": "MODIFIED",
        "revision": "source-head-sha"
      }
    ]
  },
  "comments": {
    "entries": [
      {
        "kind": "code-discussion",
        "text": "Please rename this",
        "author": {
          "name": "Leia.Organa"
        }
      }
    ]
  }
}

List changed files in a review:

{
  "name": "space_list_review_changes",
  "arguments": {
    "projectKey": "ALDERAAN",
    "review": "number:1138",
    "limit": 100
  }
}

Example response:

{
  "review": {
    "number": 1138,
    "title": "[falcon] Tune hyperdrive ignition timing"
  },
  "scope": "merge-request-files",
  "count": 1,
  "changes": [
    {
      "kind": "merge-request-file",
      "repository": "millennium-falcon",
      "path": "src/Hyperdrive.kt",
      "oldPath": "src/NavComputer.kt",
      "revision": "source-head-sha",
      "changeType": "RENAMED",
      "diffSize": {
        "added": 12,
        "deleted": 4
      }
    }
  ]
}

Filter review comments by author:

{
  "name": "space_list_review_comments",
  "arguments": {
    "projectKey": "ALDERAAN",
    "review": "number:1138",
    "author": "Leia.Organa"
  }
}

Example response:

{
  "authorFilter": "Leia.Organa",
  "count": 2,
  "comments": [
    {
      "kind": "review-feed",
      "text": "Looks good"
    },
    {
      "kind": "code-discussion",
      "anchor": {
        "filename": "src/Hyperdrive.kt",
        "line": 42
      }
    }
  ]
}

Reset Local Auth State

There is no dedicated logout tool.

To reset locally stored OAuth credentials, delete:

• $XDG_CONFIG_HOME/space-mcp-server/credentials.json, or
• ~/.config/space-mcp-server/credentials.json

Environment-based auth can be reset by removing SPACE_ACCESS_TOKEN from the MCP host configuration.

Exposed Tools

• space_auth_status
• space_authorize
• space_list_projects
• space_list_reviews
• space_list_my_reviews
• space_get_review
• space_list_review_changes
• space_list_review_comments
• space_post_review_comment
• space_create_code_discussion
• space_reply_to_discussion

Verified Space HTTP API Coverage

Verified from local Space sources and SDK references:

• Public review listing endpoint exists: GET /projects/{project}/code-reviews
• Public review details endpoint exists: GET /projects/{project}/code-reviews/{reviewId}
• Public review details-with-commits endpoint exists: GET /projects/{project}/code-reviews/{reviewId}/details
• Public review-file endpoints exist:
  • GET /projects/{project}/code-reviews/{reviewId}/merge-files
  • GET /projects/{project}/code-reviews/{reviewId}/files
• Review comments are accessible through the review feedChannelId plus chat APIs
• Public code discussion creation endpoint exists: POST /projects/{project}/code-reviews/code-discussions
• Public chat message endpoints exist for discussion replies and main review-feed comments

Known Limits

• A direct public "list my review participations" endpoint exists in source, but it is behind an internal HTTP API feature flag. This server does not depend on it.
• A public submitPendingMessages(reviewId) HTTP endpoint was not confirmed. The server can create pending messages/discussions, but reliable publication of pending drafts is not implemented.
• Cross-project "my reviews" is implemented by scanning visible projects and using public author and reviewer filters, not by a single dedicated public endpoint.

License

This repository is licensed under Apache-2.0. See LICENSE.

For publication and reference-repository audit notes, see PROVENANCE.md.