gym-mcp-server

Name	gym-mcp-server JSON
Version	0.1.0 JSON
	download
home_page	None
Summary	Expose any Gymnasium environment as an MCP server
upload_time	2025-10-08 05:28:54
maintainer	None
docs_url	None
author	Haggai Shachar
requires_python	>=3.12
license	MIT
keywords	agents ai gym gymnasium mcp model-context-protocol reinforcement-learning
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Gym MCP Server

Expose any Gymnasium environment as an MCP (Model Context Protocol) server, automatically converting the Gym API (`reset`, `step`, `render`) into MCP tools that any agent can call via standard JSON interfaces.

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Test Coverage](https://img.shields.io/badge/coverage-93%25-brightgreen.svg)](htmlcov/index.html)

## Features

- 🎮 Works with any Gymnasium environment
- 🔧 Exposes gym operations as MCP tools (`reset`, `step`, `render`, etc.)
- 🚀 Simple API with automatic serialization and error handling
- 🤖 Designed for AI agent integration (OpenAI Agents SDK, LangChain, etc.)
- 🔍 Type safe with full type hints

## Installation

```bash
pip install gym-mcp-server
```

**Requirements:** Python 3.12+

## Quick Start

### Interactive Mode

Test the server interactively:

```bash
python -m gym_mcp_server --env CartPole-v1 --interactive
```

```
> reset
Reset result: {
  "observation": [0.012, -0.034, 0.045, 0.067],
  "info": {},
  "done": false,
  "success": true
}

> step 1
Step result: {
  "observation": [0.015, 0.123, 0.042, -0.234],
  "reward": 1.0,
  "done": false,
  "truncated": false,
  "info": {},
  "success": true
}
```

### Programmatic Usage

```python
from gym_mcp_server import GymMCPAdapter

# Initialize the adapter
adapter = GymMCPAdapter("CartPole-v1")

# Reset the environment
result = adapter.call_tool("reset_env")
obs = result["observation"]

# Take an action
result = adapter.call_tool("step_env", action=1)
reward = result["reward"]
done = result["done"]

# Clean up
adapter.call_tool("close_env")
```

## Available Tools

The server exposes these MCP tools:

- **`reset_env`** - Reset to initial state (optional `seed`)
- **`step_env`** - Take an action (required `action`)
- **`render_env`** - Render current state (optional `mode`)
- **`close_env`** - Close environment and free resources
- **`get_env_info`** - Get environment metadata
- **`get_available_tools`** - List all available tools

All tools return a standardized format:

```python
{
    "success": bool,  # Whether the operation succeeded
    "error": str,     # Error message (if success=False)
    # ... tool-specific data
}
```

## Examples

### Simple Control Loop

```python
from gym_mcp_server import GymMCPAdapter

adapter = GymMCPAdapter("CartPole-v1")
obs = adapter.call_tool("reset_env")["observation"]
done = False

while not done:
    # Simple policy: move right if pole angle is positive
    action = 1 if obs[2] > 0 else 0
    result = adapter.call_tool("step_env", action=action)
    obs = result["observation"]
    done = result["done"]
    print(f"Reward: {result['reward']}")

adapter.call_tool("close_env")
```

### Random Agent

```python
import random
from gym_mcp_server import GymMCPAdapter

adapter = GymMCPAdapter("CartPole-v1")

for episode in range(5):
    adapter.call_tool("reset_env")
    done = False
    total_reward = 0
    
    while not done:
        action = random.randint(0, 1)
        result = adapter.call_tool("step_env", action=action)
        done = result["done"]
        total_reward += result["reward"]
    
    print(f"Episode {episode + 1}: {total_reward:.2f}")

adapter.call_tool("close_env")
```

### Environment Information

```python
from gym_mcp_server import GymMCPAdapter

adapter = GymMCPAdapter("CartPole-v1")
info = adapter.call_tool("get_env_info")

print(f"Action Space: {info['env_info']['action_space']}")
print(f"Observation Space: {info['env_info']['observation_space']}")

adapter.call_tool("close_env")
```

## AI Agent Integration

Works seamlessly with AI agent frameworks:

```python
from agents import Agent
from gym_mcp_server import GymMCPAdapter

adapter = GymMCPAdapter("CartPole-v1")
agent = Agent(name="GymAgent", instructions="Control the CartPole")

# Your agent can interact with the gym environment through MCP tools
```

Compatible with:
- OpenAI Agents SDK
- LangChain
- AutoGPT
- Any MCP-compatible framework

## Configuration

### Environment Variables

- `GYM_MCP_HOST`: Host to bind to (default: localhost)
- `GYM_MCP_PORT`: Port to bind to (default: 8000)
- `GYM_MCP_RENDER_MODE`: Default render mode (default: ansi)

### Command Line Options

```bash
python -m gym_mcp_server --help
```

- `--env`: Gymnasium environment ID (required)
- `--render-mode`: Default render mode
- `--interactive`: Run in interactive mode
- `--host`: Host to bind to
- `--port`: Port to bind to

## Troubleshooting

### Environment-Specific Dependencies

Some environments require additional packages:

```bash
pip install gymnasium[atari]   # For Atari environments
pip install gymnasium[box2d]   # For Box2D environments
pip install gymnasium[mujoco]  # For MuJoCo environments
```

### Python Version

Ensure you're using Python 3.12+:

```bash
python --version  # Should show 3.12 or higher
```

## Development

For development and testing:

```bash
git clone https://github.com/haggaishachar/gym-mcp-server.git
cd gym-mcp-server
make install-dev  # Install with dev dependencies
make check        # Run all checks (format, lint, typecheck, test)
```

See the [Makefile](Makefile) for all available commands.

## License

MIT License - see the LICENSE file for details.

## Links

- [GitHub Repository](https://github.com/haggaishachar/gym-mcp-server)
- [Gymnasium Documentation](https://gymnasium.farama.org/)
- [Model Context Protocol](https://modelcontextprotocol.io/)


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "gym-mcp-server",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.12",
    "maintainer_email": null,
    "keywords": "agents, ai, gym, gymnasium, mcp, model-context-protocol, reinforcement-learning",
    "author": "Haggai Shachar",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/7f/75/617281394edadb226b3ca0ecf8a84dc2cb4c03a0990f4d40d6a43c11e2df/gym_mcp_server-0.1.0.tar.gz",
    "platform": null,
    "description": "# Gym MCP Server\n\nExpose any Gymnasium environment as an MCP (Model Context Protocol) server, automatically converting the Gym API (`reset`, `step`, `render`) into MCP tools that any agent can call via standard JSON interfaces.\n\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Test Coverage](https://img.shields.io/badge/coverage-93%25-brightgreen.svg)](htmlcov/index.html)\n\n## Features\n\n- \ud83c\udfae Works with any Gymnasium environment\n- \ud83d\udd27 Exposes gym operations as MCP tools (`reset`, `step`, `render`, etc.)\n- \ud83d\ude80 Simple API with automatic serialization and error handling\n- \ud83e\udd16 Designed for AI agent integration (OpenAI Agents SDK, LangChain, etc.)\n- \ud83d\udd0d Type safe with full type hints\n\n## Installation\n\n```bash\npip install gym-mcp-server\n```\n\n**Requirements:** Python 3.12+\n\n## Quick Start\n\n### Interactive Mode\n\nTest the server interactively:\n\n```bash\npython -m gym_mcp_server --env CartPole-v1 --interactive\n```\n\n```\n> reset\nReset result: {\n  \"observation\": [0.012, -0.034, 0.045, 0.067],\n  \"info\": {},\n  \"done\": false,\n  \"success\": true\n}\n\n> step 1\nStep result: {\n  \"observation\": [0.015, 0.123, 0.042, -0.234],\n  \"reward\": 1.0,\n  \"done\": false,\n  \"truncated\": false,\n  \"info\": {},\n  \"success\": true\n}\n```\n\n### Programmatic Usage\n\n```python\nfrom gym_mcp_server import GymMCPAdapter\n\n# Initialize the adapter\nadapter = GymMCPAdapter(\"CartPole-v1\")\n\n# Reset the environment\nresult = adapter.call_tool(\"reset_env\")\nobs = result[\"observation\"]\n\n# Take an action\nresult = adapter.call_tool(\"step_env\", action=1)\nreward = result[\"reward\"]\ndone = result[\"done\"]\n\n# Clean up\nadapter.call_tool(\"close_env\")\n```\n\n## Available Tools\n\nThe server exposes these MCP tools:\n\n- **`reset_env`** - Reset to initial state (optional `seed`)\n- **`step_env`** - Take an action (required `action`)\n- **`render_env`** - Render current state (optional `mode`)\n- **`close_env`** - Close environment and free resources\n- **`get_env_info`** - Get environment metadata\n- **`get_available_tools`** - List all available tools\n\nAll tools return a standardized format:\n\n```python\n{\n    \"success\": bool,  # Whether the operation succeeded\n    \"error\": str,     # Error message (if success=False)\n    # ... tool-specific data\n}\n```\n\n## Examples\n\n### Simple Control Loop\n\n```python\nfrom gym_mcp_server import GymMCPAdapter\n\nadapter = GymMCPAdapter(\"CartPole-v1\")\nobs = adapter.call_tool(\"reset_env\")[\"observation\"]\ndone = False\n\nwhile not done:\n    # Simple policy: move right if pole angle is positive\n    action = 1 if obs[2] > 0 else 0\n    result = adapter.call_tool(\"step_env\", action=action)\n    obs = result[\"observation\"]\n    done = result[\"done\"]\n    print(f\"Reward: {result['reward']}\")\n\nadapter.call_tool(\"close_env\")\n```\n\n### Random Agent\n\n```python\nimport random\nfrom gym_mcp_server import GymMCPAdapter\n\nadapter = GymMCPAdapter(\"CartPole-v1\")\n\nfor episode in range(5):\n    adapter.call_tool(\"reset_env\")\n    done = False\n    total_reward = 0\n    \n    while not done:\n        action = random.randint(0, 1)\n        result = adapter.call_tool(\"step_env\", action=action)\n        done = result[\"done\"]\n        total_reward += result[\"reward\"]\n    \n    print(f\"Episode {episode + 1}: {total_reward:.2f}\")\n\nadapter.call_tool(\"close_env\")\n```\n\n### Environment Information\n\n```python\nfrom gym_mcp_server import GymMCPAdapter\n\nadapter = GymMCPAdapter(\"CartPole-v1\")\ninfo = adapter.call_tool(\"get_env_info\")\n\nprint(f\"Action Space: {info['env_info']['action_space']}\")\nprint(f\"Observation Space: {info['env_info']['observation_space']}\")\n\nadapter.call_tool(\"close_env\")\n```\n\n## AI Agent Integration\n\nWorks seamlessly with AI agent frameworks:\n\n```python\nfrom agents import Agent\nfrom gym_mcp_server import GymMCPAdapter\n\nadapter = GymMCPAdapter(\"CartPole-v1\")\nagent = Agent(name=\"GymAgent\", instructions=\"Control the CartPole\")\n\n# Your agent can interact with the gym environment through MCP tools\n```\n\nCompatible with:\n- OpenAI Agents SDK\n- LangChain\n- AutoGPT\n- Any MCP-compatible framework\n\n## Configuration\n\n### Environment Variables\n\n- `GYM_MCP_HOST`: Host to bind to (default: localhost)\n- `GYM_MCP_PORT`: Port to bind to (default: 8000)\n- `GYM_MCP_RENDER_MODE`: Default render mode (default: ansi)\n\n### Command Line Options\n\n```bash\npython -m gym_mcp_server --help\n```\n\n- `--env`: Gymnasium environment ID (required)\n- `--render-mode`: Default render mode\n- `--interactive`: Run in interactive mode\n- `--host`: Host to bind to\n- `--port`: Port to bind to\n\n## Troubleshooting\n\n### Environment-Specific Dependencies\n\nSome environments require additional packages:\n\n```bash\npip install gymnasium[atari]   # For Atari environments\npip install gymnasium[box2d]   # For Box2D environments\npip install gymnasium[mujoco]  # For MuJoCo environments\n```\n\n### Python Version\n\nEnsure you're using Python 3.12+:\n\n```bash\npython --version  # Should show 3.12 or higher\n```\n\n## Development\n\nFor development and testing:\n\n```bash\ngit clone https://github.com/haggaishachar/gym-mcp-server.git\ncd gym-mcp-server\nmake install-dev  # Install with dev dependencies\nmake check        # Run all checks (format, lint, typecheck, test)\n```\n\nSee the [Makefile](Makefile) for all available commands.\n\n## License\n\nMIT License - see the LICENSE file for details.\n\n## Links\n\n- [GitHub Repository](https://github.com/haggaishachar/gym-mcp-server)\n- [Gymnasium Documentation](https://gymnasium.farama.org/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Expose any Gymnasium environment as an MCP server",
    "version": "0.1.0",
    "project_urls": {
        "Homepage": "https://github.com/haggaishachar/gym-mcp-server",
        "Issues": "https://github.com/haggaishachar/gym-mcp-server/issues",
        "Repository": "https://github.com/haggaishachar/gym-mcp-server"
    },
    "split_keywords": [
        "agents",
        " ai",
        " gym",
        " gymnasium",
        " mcp",
        " model-context-protocol",
        " reinforcement-learning"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "139bc8afdc605218c6a73138937c8d4be927f6de230289f694071fce8a719e78",
                "md5": "211863a74d795fb2b05fa45d30383bbc",
                "sha256": "cc2162ca2cc0a372d1caf11d54b4f04e862d6539c3d8c86903c5407f686be9ae"
            },
            "downloads": -1,
            "filename": "gym_mcp_server-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "211863a74d795fb2b05fa45d30383bbc",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.12",
            "size": 9655,
            "upload_time": "2025-10-08T05:28:53",
            "upload_time_iso_8601": "2025-10-08T05:28:53.007253Z",
            "url": "https://files.pythonhosted.org/packages/13/9b/c8afdc605218c6a73138937c8d4be927f6de230289f694071fce8a719e78/gym_mcp_server-0.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "7f75617281394edadb226b3ca0ecf8a84dc2cb4c03a0990f4d40d6a43c11e2df",
                "md5": "b5c46808ef6cc7396c2412190d9a6461",
                "sha256": "4037b2e89313ef105876b703dceeab64bbcec734c0467dbc1e2681f991e3dccd"
            },
            "downloads": -1,
            "filename": "gym_mcp_server-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "b5c46808ef6cc7396c2412190d9a6461",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.12",
            "size": 125292,
            "upload_time": "2025-10-08T05:28:54",
            "upload_time_iso_8601": "2025-10-08T05:28:54.786039Z",
            "url": "https://files.pythonhosted.org/packages/7f/75/617281394edadb226b3ca0ecf8a84dc2cb4c03a0990f4d40d6a43c11e2df/gym_mcp_server-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-08 05:28:54",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "haggaishachar",
    "github_project": "gym-mcp-server",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "gym-mcp-server"
}