---
slug: "playfab-mcp-server"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/akiojin/playfab-mcp-server@main/README.md"
repo: "https://github.com/akiojin/playfab-mcp-server"
source_file: "README.md"
branch: "main"
---
# PlayFab MCP Server

## What Is This? 🤔

This server is a middleware that enables large language models (like Claude and VS Code) to interact directly with PlayFab services. Acting as a secure and efficient translator, it connects your AI assistant with various PlayFab functionalities, such as item search, segment inquiries, player profile lookups, inventory management, and PlayFab ID conversion.

### Quick Example

```text
You: "Show me the latest 10 items."
Claude: *calls the PlayFab search_items API and returns the results in plain text*
```

## How Does It Work? 🛠️

This server leverages the Model Context Protocol (MCP) to establish a universal interface between AI models and PlayFab services. Although MCP is designed to support any AI model, it is currently available as a developer preview.

Follow these steps to get started:

1. Set up your project.
2. Add your project details to your LLM client's configuration.
3. Start interacting with PlayFab data naturally!

### What Can It Do? 📊

#### Catalog & Search

- Search for items using PlayFab's search_items API.
- **Catalog Management (Economy v2):**
  - Create new draft items with the create_draft_item API.
  - Update existing draft items with the update_draft_item API.
  - Delete items from catalog with the delete_item API.
  - Publish draft items to make them available with the publish_draft_item API.
  - Get detailed item information with the get_item API.

#### Player Management

- Retrieve comprehensive segment information.
- Query player profiles within specified segments.
- Convert a PlayFab ID to a Title Player Account ID via the get_title_player_account_id_from_playfab_id API.
- Get detailed user account information with the get_user_account_info API.

#### Inventory Management

- **Get Operations:**
  - Retrieve current inventory items with the get_inventory_items API.
  - Fetch inventory collection IDs using the get_inventory_collection_ids API.
- **Add/Remove Operations:**
  - Add items to inventory with the add_inventory_items API.
  - Delete items from inventory with the delete_inventory_items API.
  - Subtract specific amounts with the subtract_inventory_items API.
- **Modify Operations:**
  - Update item properties with the update_inventory_items API.

#### Economy v2 Administration

- Execute batch inventory operations with the execute_inventory_operations API.
- Note: In Economy v2, virtual currencies are managed as inventory items.

#### User Account Administration

- Ban players by ID, IP, or MAC address with the ban_users API.
- Unban players completely with the revoke_all_bans_for_user API.

#### Player Data Management

- Retrieve player custom data with the get_user_data API.
- Update player custom data with the update_user_data API.

#### Title Configuration Management

- Set global title data with the set_title_data API.
- Retrieve title data with the get_title_data API.
- Set server-only internal data with the set_title_internal_data API.
- Retrieve internal data with the get_title_internal_data API.

## Quick Start 🚀

### Prerequisites

- Node.js 18 or higher.
- A valid PlayFab account (obtain your Title ID and Developer Secret Key via PlayFab Game Manager).
- A supported LLM client such as Claude Desktop.

### Set Up Your Project

Obtain your PlayFab Title ID and Developer Secret Key from the PlayFab Game Manager, then create a `.env` file in the project root with the following content (replace the placeholders with your actual credentials):

```bash
PLAYFAB_TITLE_ID=
PLAYFAB_DEV_SECRET_KEY=
```

### Installation and Setup

1. **Install Dependencies**

   In the project root, run the following command to install all necessary dependencies:

   ```bash
   npm install
   ```

2. **Build the Project**

   Compile the project by executing:

   ```bash
   npm run build
   ```

3. **Start the Server**

   Start the server by executing:

   ```bash
   npm start
   ```

4. **Confirmation Message**

   Upon startup, you should see this message:

   ```text
   PlayFab Server running on stdio
   ```

### Development Setup

#### Code Quality Tools

- **ESLint**: Configured for TypeScript with recommended rules for code consistency
- **Prettier**: Automatic code formatting with project-specific settings
- **TypeScript**: Strict mode enabled for enhanced type safety
- **Jest**: Testing framework configured for TypeScript

#### Available Scripts

```bash
# Build the project
npm run build

# Development mode with file watching
npm run watch

# TypeScript type checking
npm run typecheck

# Run ESLint
npm run lint

# Run ESLint and fix issues
npm run lint:fix

# Format code with Prettier
npm run format

# Check code formatting
npm run format:check

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

#### TypeScript Configuration

This project uses TypeScript with strict mode enabled, ensuring:
- Strict null checks
- No implicit any types
- Strict function types
- Always strict mode

#### Testing

Tests are written using Jest and can be found in `__tests__` directories or files with `.test.ts` extension. Run tests before committing changes to ensure code quality.

### Spec-Driven Development (Spec Kit, JP)

- Install CLI: `uv tool install specify-cli --from git+https://github.com/akiojin/spec-kit.git`
- Create spec/plan/tasks: `./.specify/scripts/bash/create-new-feature.sh "feature summary"`（デフォルトはブランチを作成しない。必要なら `--branch`）
- Assets: `.specify/templates/*`, `.specify/scripts/bash/*`, specs under `specs/`
- Claude/Codex slash commands: `/speckit.constitution`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, `/speckit.implement`

### Docker Development Environment

The repository ships with a lightweight dev container (Node 22, tooling, GitHub CLI).

```bash
# Build image
docker compose build

# Open a shell inside the container
docker compose run --rm playfab-mcp-server bash

# Inside the container
npm ci
npm run build
npm start
```

Volumes keep your workspace (`.`), Codex/Claude configs, and shell history. Set `PLAYFAB_TITLE_ID` / `PLAYFAB_DEV_SECRET_KEY` in the container env when running the server.

### Running with Cursor

To use the PlayFab MCP server with Cursor, follow these steps:

1. Install [Cursor Desktop](https://cursor.so/) if you haven't already.
2. Open a new instance of Cursor in an empty folder.
3. Copy the [`mcp.json`](https://github.com/akiojin/playfab-mcp-server/blob/HEAD/.cursor/mcp.json) file from this repository into your folder and update the values according to your environment.
4. Launch Cursor; the PlayFab MCP Server should appear in the tools list.
5. For example, try a prompt like "Show me the latest 10 items" to verify that the server processes your query correctly.

### Adding Your Project Details to Claude Desktop's Config File

Open Claude Desktop and navigate to File → Settings → Developer → Edit Config. Then, replace the `claude_desktop_config` file content with the following snippet:

```json
{
  "mcpServers": {
    "playfab": {
      "command": "npx",
      "args": [
        "-y",
        "@akiojin/playfab-mcp-server"
      ],
      "env": {
        "PLAYFAB_TITLE_ID": "Your PlayFab Title ID",
        "PLAYFAB_DEV_SECRET_KEY": "Your PlayFab Developer Secret Key"
      }
    }
  }
}
```

With these steps, you have successfully configured the PlayFab MCP server for use with your LLM client, allowing seamless interaction with PlayFab's services.

## Spec-Driven Development with Spec Kit

This repository follows the Spec Kit SDD/TDD workflow used in `akiojin/gwt`.

- Requirements: Python 3.11+ and `uv`
- Install CLI: `uv tool install specify-cli --from git+https://github.com/akiojin/spec-kit.git`
- Assets: templates under `.specify/templates`, scripts under `.specify/scripts/bash`, specs live in `specs/`
- Create a new spec/plan: `./.specify/scripts/bash/create-new-feature.sh "feature summary"` (add `--branch` if you also want a branch)
- Generated files include `spec.md`, `plan.md`, `tasks.md`; keep them reviewed/committed alongside code
- Claude/Codex slash commands (if available): `/speckit.constitution`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, `/speckit.implement`

## Contributing

### Commit Message Convention

This project follows [Conventional Commits](https://www.conventionalcommits.org/) for automated versioning and release.

#### Commit Message Format

```text
<type>(<scope>): <subject>

<body>

<footer>
```

#### Types

- **feat**: A new feature (triggers MINOR version bump)
- **fix**: A bug fix (triggers PATCH version bump)
- **docs**: Documentation only changes
- **style**: Changes that do not affect the meaning of the code
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **perf**: A code change that improves performance
- **test**: Adding missing tests or correcting existing tests
- **chore**: Changes to the build process or auxiliary tools

#### Version Bumping Rules

- **MAJOR** version: When commit message contains `BREAKING CHANGE` in footer or `!` after type/scope
  - Example: `feat!: remove deprecated API endpoints`
  - Example: `feat: new API\n\nBREAKING CHANGE: removed old endpoints`
- **MINOR** version: When commit type is `feat`
  - Example: `feat: add new PlayFab API integration`
- **PATCH** version: When commit type is `fix`
  - Example: `fix: correct error handling in API calls`

### Release Process (develop → main, release-please)

1. **Prepare release PR**: Run the `prepare-release.yml` workflow to open a PR from `develop` to `main`  
   - Actions UI: `Prepare Release` → run with ref `develop`  
   - CLI: `gh workflow run prepare-release.yml --ref develop`  
   - If a PR from `develop` already exists, it will be reused; PRs opened from `develop` can be auto-merged by the workflow.
2. **Release automation**: When `main` is updated, `release.yml` runs release-please (manifest) to bump versions, update `CHANGELOG.md`, and create the GitHub Release/tag.
3. **Publish**: Tag push `v*` triggers `publish.yml` to run tests, build, typecheck, and `npm publish --access public`.

Required secrets:
- `PERSONAL_ACCESS_TOKEN` (optional; used by `prepare-release`/`release` when provided, falls back to `GITHUB_TOKEN`)
- `NPM_TOKEN` (for `publish.yml`)

Branch protection: keep protections on `main`; release PRs should satisfy required checks before merge.

### Scripts Reference

| Script | Description |
|--------|-------------|
| `npm start` | Start the MCP server |
| `npm run build` | Build TypeScript to JavaScript |
| `npm run watch` | Build in watch mode for development |
| `npm run typecheck` | Run TypeScript type checking |
| `npm run lint` | Run ESLint checks |
| `npm run lint:fix` | Fix ESLint issues automatically |
| `npm run format` | Format code with Prettier |
| `npm run format:check` | Check code formatting |
| `npm test` | Run all tests |
| `npm run test:watch` | Run tests in watch mode |
| `npm run test:coverage` | Generate test coverage report |

## Security

We take security seriously. If you discover a security vulnerability within this project, please follow these steps:

### Reporting Security Vulnerabilities

1. **DO NOT** create a public GitHub issue for security vulnerabilities
2. Instead, please report security issues via GitHub's private vulnerability reporting:
   - Go to the **Security** tab of this repository
   - Click on **Report a vulnerability**
   - Provide detailed information about the vulnerability

### What We Need From You

- A description of the vulnerability
- Steps to reproduce the issue
- Potential impact
- Any suggested fixes (optional)

### Our Commitment

- We will acknowledge receipt of your report within 48 hours
- We will provide regular updates on our progress
- We will credit you for the discovery (unless you prefer to remain anonymous)

### Security Best Practices

When using this server:

1. **Never commit credentials**: Always use environment variables for sensitive data
2. **Keep dependencies updated**: Regularly run `npm audit` and update packages
3. **Use least privilege**: Only grant the minimum required permissions
4. **Rotate keys regularly**: Change your PlayFab Developer Secret Keys periodically

## Support

### Getting Help

If you encounter any issues or have questions about using the PlayFab MCP Server, here are the best ways to get support:

1. **GitHub Issues**: For bug reports and feature requests, please [create an issue](https://github.com/akiojin/playfab-mcp-server/issues)
2. **Discussions**: For general questions and community support, use [GitHub Discussions](https://github.com/akiojin/playfab-mcp-server/discussions)
3. **Documentation**: Check the README and code comments for usage examples

### Before Creating an Issue

Please check if your issue has already been reported by searching existing issues. If you find a similar issue, you can add additional information as a comment.

### What We Support

- Installation and setup questions
- Bug reports with reproducible steps
- Feature requests and suggestions
- Documentation improvements

### What We Don't Support

- General PlayFab API questions (please refer to [PlayFab Documentation](https://docs.microsoft.com/gaming/playfab/))
- Issues with third-party tools or services
- Custom implementation requests

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/akiojin/playfab-mcp-server/tree/HEAD/LICENSE) file for details.