# floci-mcp

MCP server that lets an AI agent deploy and manage AWS-shaped resources on a
local [Floci](https://github.com/Awilliv/floci) instance — "spin up an EC2
instance with these parameters," "create an S3 bucket and a DynamoDB
table," and so on.

## What it does

Floci emulates 76 AWS services on `http://localhost:4566`. `floci-mcp`
exposes that endpoint to any MCP-compatible client as three tools:

- **`aws_call(service, action, params)`** — call any AWS API operation (any
  service, any action) against Floci. This is the core tool: since it's a
  thin pass-through to the AWS API, it covers all 76 services without a
  hand-built tool per operation.
- **`floci_status()`** — check whether Floci is reachable.
- **`floci_inventory()`** — summarize what's currently deployed across S3,
  DynamoDB, Lambda, EC2, SQS, SNS, ECS, and RDS in one call.

## Prerequisites

- Python 3.10+
- A running Floci instance — see the
  [Floci README](https://github.com/Awilliv/floci) for `floci start` or
  Docker setup.

## Install

From a clone (not yet published to PyPI):

```bash
git clone https://github.com/Awilliv/floci-mcp.git
cd floci-mcp
pip install -e .
```

Once published to PyPI:

```bash
pip install floci-mcp
```

## Configuration

Environment variables, all optional:

| Variable | Default | Purpose |
|---|---|---|
| `FLOCI_ENDPOINT_URL` | `http://localhost:4566` | Floci's HTTP endpoint |
| `AWS_DEFAULT_REGION` | `us-east-1` | Region passed to every boto3 client |
| `AWS_ACCESS_KEY_ID` | `test` | Credential; a 12-digit value selects a Floci account (multi-account isolation) |
| `AWS_SECRET_ACCESS_KEY` | `test` | Credential (any non-empty value works against Floci) |

## Usage examples

Once registered with an MCP client, ask the agent things like:

> "Spin up an EC2 instance with a t3.micro instance type using
> ami-00000000"

> "Create an S3 bucket called `reports` and a DynamoDB table called `users`
> with a partition key `id`"

The agent drives these through `aws_call` — it already knows AWS API
parameter shapes, so no per-service tool needs to exist for it to work.

## Registering with an MCP client

### Claude Code

Setting `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` explicitly here (rather than relying on the launching shell's environment) avoids accidentally signing requests with real AWS credentials if you happen to have them exported elsewhere.

```bash
claude mcp add floci -- floci-mcp
```

Or add to `.mcp.json`:

```json
{
  "mcpServers": {
    "floci": {
      "command": "floci-mcp",
      "env": {
        "FLOCI_ENDPOINT_URL": "http://localhost:4566",
        "AWS_ACCESS_KEY_ID": "test",
        "AWS_SECRET_ACCESS_KEY": "test"
      }
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "floci": {
      "command": "floci-mcp",
      "env": {
        "FLOCI_ENDPOINT_URL": "http://localhost:4566",
        "AWS_ACCESS_KEY_ID": "test",
        "AWS_SECRET_ACCESS_KEY": "test"
      }
    }
  }
}
```

### Open WebUI (via mcpo)

Open WebUI speaks OpenAPI/tool-calling, not MCP directly. Front
`floci-mcp` with [`mcpo`](https://github.com/open-webui/mcpo) to expose it
as an OpenAPI server:

```bash
pip install mcpo
mcpo --port 8000 -- floci-mcp
```

Then in Open WebUI, go to **Settings → Tools → Add a Tool Server** and add
`http://localhost:8000`. `mcpo` passes environment variables through to the
`floci-mcp` process it launches, so set `FLOCI_ENDPOINT_URL` etc. in the
shell you run `mcpo` from before starting it.

## Development

```bash
pip install -e ".[test]"
pytest
```

Integration tests in `tests/test_integration.py` require a running Floci
instance and skip themselves automatically when one isn't reachable.

## License

MIT