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.

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

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!

• 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.

• 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.

• 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.

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

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

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

• 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.

• 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.

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):

PLAYFAB_TITLE_ID=
PLAYFAB_DEV_SECRET_KEY=

1. Install Dependencies

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

   npm install

2. Build the Project

   Compile the project by executing:

   npm run build

3. Start the Server

   Start the server by executing:

   npm start

4. Confirmation Message

   Upon startup, you should see this message:

   PlayFab Server running on stdio
   

• 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

# 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

This project uses TypeScript with strict mode enabled, ensuring:

• Strict null checks
• No implicit any types
• Strict function types
• Always strict mode

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.

• 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

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

# 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.

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

1. Install Cursor Desktop if you haven't already.
2. Open a new instance of Cursor in an empty folder.
3. Copy the 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.

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

{
  "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.

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

This project follows Conventional Commits for automated versioning and release.

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

<body>

<footer>

• 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

• 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

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.

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

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

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

• 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)

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

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
2. Discussions: For general questions and community support, use GitHub Discussions
3. Documentation: Check the README and code comments for usage examples

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.

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

• General PlayFab API questions (please refer to PlayFab Documentation)
• Issues with third-party tools or services
• Custom implementation requests

This project is licensed under the MIT License - see the LICENSE file for details.