Gooseworks MCP

An Express server that exposes tools through the Model Context Protocol (MCP) Streamable HTTP transport, including a set of GitHub tools.

The MCP endpoint is:

http://localhost:4000/mcp

Every request must include the bearer token configured by MCP_AUTH_TOKEN.

Requirements

• Node.js v25.2.1

• pnpm 11.5.3

• Docker Engine and Docker Compose v2 for container deployment

• A GitHub personal access token with the permissions required by the tools you plan to use

Configuration

The server loads variables from a local .env file or the process environment:

Create a local environment file from the template:

cp .env.template .env

Edit .env and replace both placeholder token values. Use a long, randomly generated value for MCP_AUTH_TOKEN, and grant the GitHub token only the permissions needed by this server. Never commit .env or paste either token into a public issue, log, or image.

Run Locally

1. Install dependencies:

   pnpm install

2. Create and configure .env as described above.

3. Start the server:

   pnpm start

   This runs the same entrypoint as pnpm exec tsx src/index.ts.

For development with automatic restart after source changes, use:

pnpm dev

To check the TypeScript project without emitting files:

pnpm typecheck

The server is ready when the console reports that it is active on http://localhost:<PORT>/mcp. Configure your MCP client to use that URL and send:

Authorization: Bearer <MCP_AUTH_TOKEN>

Deploy With Docker Compose

1. Install Docker Engine with Docker Compose v2 on the host.

2. Clone this repository and enter its directory:

   git clone <repository-url>
   cd gooseworks-mcp

3. Create the deployment environment file:

   cp .env.template .env

4. Set GITHUB_TOKEN and a strong, private MCP_AUTH_TOKEN in .env. Set PORT if the service should listen on a different host/container port. The same value is used for both sides of the Compose port mapping.

5. Build and start the service in the background:

   docker compose up --build -d

6. Follow the service logs or stop it when needed:

   docker compose logs -f gooseworks-mcp
   docker compose down

The Compose configuration passes the three supported variables into the container and fails early if either required token is missing. For a public deployment, place the service behind an HTTPS reverse proxy and keep port 4000 or your chosen PORT private when possible. MCP clients should use the proxy's HTTPS /mcp URL and the configured bearer token.

Available Tools

The server registers the following tools:

GitHub

• Reading the authenticated profile

• Listing repositories, branches, and commits

• Searching code

• Reading file contents

• Creating issues

• Creating pull requests

License

This project is licensed under the MIT License. It is free to use, fork, modify, and redistribute for any purpose, subject to the license terms.