TheValverde/spacetraders-mcp

SpaceTraders MCP Server

A Model Context Protocol (MCP) server for interacting with the SpaceTraders API. This server exposes SpaceTraders API endpoints as MCP tools, allowing AI agents to manage agents, fleets, contracts, and trading operations in the SpaceTraders universe.

Overview

This project provides an MCP server that enables AI agents to:

• Register and manage SpaceTraders agents
• View and manage ships and fleets
• Accept, deliver, and fulfill contracts
• Trade resources and interact with markets
• Explore systems, waypoints, and shipyards

The implementation is based on the MCP standard, using the mcp Python package for server infrastructure.

Features

• Register new SpaceTraders agents
• View agent details and list agents
• List, view, accept, deliver, and fulfill contracts
• List ships, view ship details, purchase ships
• Navigate, dock, orbit, refuel, and extract resources with ships
• Transfer and sell cargo
• Scan systems, waypoints, and ships
• View markets and shipyards
• Chart waypoints and refine resources

See TODO.md for a detailed checklist of implemented and missing endpoints.

Prerequisites

• Python 3.12+
• SpaceTraders API key (from https://my.spacetraders.io)
• Docker (optional, for containerized deployment)

Installation

Using uv

1. Install uv if you don't have it:

   pip install uv
   

2. Clone this repository:

   git clone https://github.com/TheValverde/spacetraders-mcp.git
   cd spacetraders-mcp
   

3. Install dependencies:

   uv pip install -e .
   

4. Create a .env file in the project root and add your SpaceTraders API key:

   SPACETRADERS_API_KEY=your-api-key-here
   

Using Docker (optional)

1. Build the Docker image:

   docker build -t spacetraders-mcp .
   

2. Create a .env file in the project root and add your SpaceTraders API key.

Configuration

The following environment variable is required:

Running the Server

Using uv

uv run src/main.py

Using Docker

docker run --env-file .env -p 8050:8050 spacetraders-mcp

MCP Integration

This server exposes SpaceTraders API endpoints as MCP tools. You can connect to it from any MCP-compatible client. Example configuration (update URL/port as needed):

{
  "mcpServers": {
    "spacetraders": {
      "transport": "sse",
      "url": "http://localhost:8050/sse"
    }
  }
}

Project Structure

• src/main.py — Main MCP server implementation and tool definitions
• src/spacetraders_utils.py — SpaceTraders API client and token management
• src/utils.py — Utility functions
• agent_tokens.json — Persistent agent tokens (auto-managed)
• schemas/ — OpenAPI and reference JSON files for SpaceTraders API
• public/ — Static assets
• TODO.md — Endpoint implementation checklist

Schemas and Reference Data

The schemas/ directory contains large JSON files used for reference and development:

• schemas/SpaceTraders.json — The official OpenAPI specification for the SpaceTraders API (v2). Used for endpoint reference and validation.
• schemas/SpaceTraderFullAPI.json — (Describe usage here if different, or remove if unused.)

These files are not required for running the server, but are useful for development, code generation, and documentation.

Development Status

See TODO.md for a list of implemented and missing endpoints. The core gameplay and trading endpoints are implemented; some advanced features are still TODO.

This project is licensed under the terms described in the LICENSE file included in this repository.